Miner U MCP

MCP文档知识

提供方 AvatarGanymede

文档知识 stdio · 本地进程 API Key 社区 / 第三方 Claude DesktopClaudeCursor
查看接入方式

一个通过MinerU API将多种格式文档转换为Markdown格式的服务器,支持URL和本地文件输入,具备OCR、公式识别、表格识别等功能。

一句话选型结论

按资料字段整理

Miner U MCP 属于文档知识类 MCP 服务器,stdio · 本地进程,API Key,可直接接入 Claude Desktop、Claude、Cursor,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类文档知识 传输方式stdio · 本地进程 鉴权API Key 部署方式本地部署
GitHub 星标 3 仓库热度,无公开仓库时显示未标注
工具数 4 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

文档知识
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量4暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

支持客户端

适用场景

文档转换Python本地部署Markdown生成OCR处理大文件处理多格式支持

安装与配置

stdio · 本地进程 API Key
客户端在本机拉起子进程,数据不出本机
pip install -r requirements.txt

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 Node.js 等运行时,再按安装命令拉取依赖。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后客户端会列出约 4 个工具,随便调一个只读工具确认能返回结果。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
文档检索问答

在你的文档库里按问题找答案。

知识库读写

把新资料写进知识库,随用随取。

内容整理

把零散资料归纳成结构化笔记。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 资料标注 4 个工具,职责相对集中,接入后不容易误操作。
  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。
  • 已适配 Claude Desktop、Claude、Cursor,换客户端不用重新研究配置。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 使用前要准备好API Key对应的凭据,并按最小权限配置。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在文档知识场景里让模型直接调用外部能力的人。
  • 已经在用 Claude Desktop、Claude 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 不方便管理密钥或第三方授权的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
Miner U MCP当前 4 stdio · 本地进程 本地部署 有 2026-05-17
dify 未标注 stdio · 本地进程 本地部署 有 2026-04-11
open-webui 未标注 stdio · 本地进程 本地部署 有 2026-04-11
JeecgBoot 未标注 stdio · 本地进程 本地部署 有 2026-04-11
Cherry Studio 未标注 未标注 未标注 无 2026-05-17
mempalace 未标注 stdio · 本地进程 本地部署 有 2026-04-11

服务器档案

文档知识
字段来自项目仓库与公开索引,中文说明由本站标注
提供方AvatarGanymede上游标注的维护方 AvatarGanymede
分类文档知识本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式API Key远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · 未标注本地安装时用到的包标识与运行时
部署类型本地部署上游给出的部署形态
最近核验2026-05-17上游最后核验时间

详细介绍

11.4 KB
来自项目仓库与上游目录的原文,未做删改

MinerU Document to Markdown MCP Server

English | 中文

一个 Model Context Protocol (MCP) 服务器,用于通过 MinerU API 将多种格式文档转换为 Markdown 格式。支持 URL 和本地文件两种输入方式。

功能特点

  • 🔄 使用 Python requests 调用 MinerU API
  • 📄 支持多种格式:PDF, DOC, DOCX, PPT, PPTX, PNG, JPG, JPEG, HTML
  • 📁 支持本地文件自动上传解析
  • 🔍 支持 OCR、公式识别、表格识别
  • 🧠 智能参数自动配置(根据文件类型自动选择模型和参数)
  • 📦 大文件智能拆分(>200MB 自动物理拆分,>600 页自动使用 page_ranges)
  • ⚡ 提供完整的转换工作流(提交任务 → 轮询状态 → 获取结果)

安装

1. 安装依赖```bash

pip install -r requirements.txt


### 2. 获取 MinerU API Token

访问 https://mineru.net 注册并申请 API Token。

### 3. 配置 MCP 客户端

#### 方式一:uvx 启动(推荐,无需手动安装依赖)

安装 uv 后,可直接通过 `uvx` 运行,无需 `pip install`:```bash
uvx mineru-converter-mcp-server stdio

编辑 Claude Desktop 或 Cursor MCP 配置文件:

Windows: %APPDATA%\Claude\claude_desktop_config.json 或 Cursor 设置中的 MCP 配置
macOS: `~/Library/Application Support/Claude/claude_desktop_config.json````json
{
"mcpServers": {
"mineru": {
"command": "uvx",
"args": ["--with", "mineru-converter-mcp-server", "python", "-m", "mineru_mcp", "stdio"],
"env": {
"MINERU_API_KEY": "your_mineru_api_token"
}
}
}
}


> **说明**:使用 `-m mineru_mcp` 模块方式启动,可规避 Windows 下 uvx console script 的兼容问题。开发阶段可从源码安装:`uv pip install -e .` 后使用 `mineru-converter-mcp-server stdio`。

#### 方式二:Python 版(功能完整,支持本地文件和大文件拆分)

需先安装依赖:`pip install -r requirements.txt`

编辑 Claude Desktop 配置文件:

**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json````json
{
  "mcpServers": {
    "mineru": {
      "command": "python",
      "args": ["src/mineru_mcp/server.py"],
      "cwd": "C:/path/to/MinerU-MCP",
      "env": {
        "MINERU_API_KEY": "your_mineru_api_token"
      }
    }
  }
}

> 将 C:/path/to/MinerU-MCP 替换为项目实际路径。cwd 确保从项目根目录运行。

方式三:TypeScript 版(适用于 Smithery 部署和本地开发)

需要先安装 Node.js 20+ 和项目依赖:```bash
npm install


在项目根目录创建 `.mcp.json`(Claude Code)或编辑 `claude_desktop_config.json`(Claude Desktop):

**macOS / Linux:**```json
{
  "mcpServers": {
    "mineru": {
      "command": "npx",
      "args": ["tsx", "src/main.ts"],
      "env": {
        "MINERU_API_KEY": "your_mineru_api_token"
      }
    }
  }
}

Windows:```json
{
"mcpServers": {
"mineru": {
"command": "cmd",
"args": ["/c", "npx", "tsx", "src/main.ts"],
"env": {
"MINERU_API_KEY": "your_mineru_api_token"
}
}
}
}


> **注意**:TypeScript 版仅支持 URL 输入,不支持本地文件上传和大文件拆分。如需这些功能请使用 Python 版。

**本地 HTTP 服务**(可选):`npm run start:http` 或 `MINERU_API_KEY=xxx npx tsx src/server-http.ts`,默认监听 10000 端口,暴露 `/mcp` 和 `/.well-known/mcp-config`。

两种方式均需将 `your_mineru_api_token` 替换为你的 MinerU API Token(在 https://mineru.net/apiManage/token 申请)。

### 部署到 Render(Deploy via URL,免费)

使用 Render 将 TypeScript 版 MCP 部署为公开 HTTPS 服务,然后在 Smithery 选择「Deploy via URL」即可免费分发。**无需 smithery dev**,自建 HTTP 服务即可运行。

1. **Fork 并推送**:确保本仓库代码已推送到 GitHub
2. **创建 Blueprint**:打开 Render Dashboard → New → Blueprint
3. **连接仓库**:选择 `MinerU-MCP` 仓库,Render 会自动读取根目录的 `render.yaml`
4. **部署**:点击 Create / Apply,等待构建完成
5. **获取 URL**:部署完成后会得到 `https://mineru-mcp.onrender.com` 之类的 HTTPS 地址
6. **登记到 Smithery**:
   - **网页**:在 Smithery New Server 选择 External MCP / Deploy via URL,填入上述 URL(会有 config schema 警告,可忽略;用户在 Add Parameter 中手动填 `mineruApiKey`)
   - **CLI(推荐,消除警告)**:`smithery auth login` 登录后执行:```bash
     smithery mcp publish "https://你的Render地址/mcp" -n @你的命名空间/mineru-mcp --config-schema '{"type":"object","properties":{"mineruApiKey":{"type":"string","title":"MinerU API Key","description":"Your MinerU API Key (obtain from https://mineru.net/apiManage/token)","x-from":{"header":"x-mineru-api-key"}}}}'
     ```

> **Smithery Deploy via URL**:不设置 `MINERU_API_KEY`,每个用户会在 Smithery 添加 MCP 时填写自己的 API Key。
>
> **自托管单租户**:在 Render Environment 中设置 `MINERU_API_KEY`,则所有请求共用该 Key。

## 支持的文件格式

| 格式 | 扩展名 | 自动配置 |
|------|--------|---------|
| PDF | .pdf | 默认使用 vlm 模型 |
| Word | .doc, .docx | 默认使用 vlm 模型 |
| PowerPoint | .ppt, .pptx | 默认使用 vlm 模型 |
| 图片 | .png, .jpg, .jpeg | 自动开启 OCR |
| 网页 | .html | 自动使用 MinerU-HTML 模型 |

## 大文件处理

服务器自动处理超大文件,无需手动干预:

- **文件 >200MB(仅 PDF)**:自动物理拆分为多个小文件,分别处理后返回结果
- **文件 >600 页(仅 PDF)**:自动使用 page_ranges 参数分段处理
- **拆分算法**:同时考虑文件大小(180MB/片)和页数(600页/片)双重约束,取较大值确保每个分片同时满足两个限制

## 使用方法

### 工具 1: create_parse_task

创建一个文档解析任务。支持 URL 或本地文件路径,本地文件会自动上传。

**参数:**
- `url` (必需): 文档的 URL 或本地文件路径(支持 PDF, DOC, DOCX, PPT, PPTX, PNG, JPG, JPEG, HTML)
- `model_version` (可选): 模型版本,根据文件类型自动选择(vlm / pipeline / MinerU-HTML)
- `is_ocr` (可选): 是否启用 OCR(图片格式自动启用),默认 `false`
- `enable_formula` (可选): 是否启用公式识别,默认 `true`
- `enable_table` (可选): 是否启用表格识别,默认 `true`

**返回值:**
- URL 输入:返回 `task_id`
- 本地文件输入:返回 `batch_id`
- 大文件拆分:返回 `batch_ids` 列表

**示例:**```
# PDF 文件
请解析这个 PDF:https://example.com/report.pdf

# Word 文档
请解析本地 Word 文档:C:/Documents/report.docx

# PowerPoint 文件
请解析本地 PPT:C:/Documents/slides.pptx

# 图片(自动 OCR)
请解析这张图片:C:/Documents/scan.png

# HTML 网页
请解析本地 HTML:C:/Documents/page.html

工具 2: get_task_status

查询任务状态。支持通过 task_id(URL 解析)或 batch_id(本地文件上传)查询。

参数:
- task_id (可选): 任务 ID(URL 方式创建的任务)
- batch_id (可选): 批量任务 ID(本地文件上传创建的任务)

> 两个参数至少提供一个。

工具 3: download_result

下载解析结果 zip 文件。

参数:
- zip_url (必需): 结果文件的 URL
- output_path (必需): 本地保存路径

工具 4: convert_to_markdown (推荐)

完整的转换工作流,自动提交任务、等待完成并下载结果。支持所有格式的 URL 或本地文件路径。

参数:
- url (必需): 文档的 URL 或本地文件路径
- output_path (必需): 结果 zip 文件的本地保存路径
- model_version (可选): 模型版本(自动检测),默认 vlm
- max_wait_seconds (可选): 最大等待时间(秒),默认 300
- poll_interval (可选): 轮询间隔(秒),默认 10

示例:```

转换 PDF

帮我把这个 PDF 转成 Markdown:
url: C:/Documents/report.pdf
output_path: C:/output/result.zip

转换 Word 文档

帮我把这个 Word 文档转成 Markdown:
url: C:/Documents/report.docx
output_path: C:/output/result.zip

转换 PPT

帮我把这个 PPT 转成 Markdown:
url: C:/Documents/slides.pptx
output_path: C:/output/result.zip


> 注:`convert_pdf_to_markdown` 仍可使用(向后兼容),功能与 `convert_to_markdown` 完全相同。

## Claude Code Skill 快捷用法

本项目提供了 `/convert-to-markdown` skill,可在 Claude Code 中通过斜杠命令快速调用文档转 Markdown 功能。

### 基本用法```
/convert-to-markdown <文档路径或URL> [指令]

示例```bash

转换 PDF

/convert-to-markdown C:/Documents/report.pdf 分析并总结这个文档内容

转换 Word 文档

/convert-to-markdown C:/Documents/report.docx 提取文档要点

转换 PPT

/convert-to-markdown C:/Documents/slides.pptx

转换图片

/convert-to-markdown C:/Documents/scan.png 识别图片中的文字
```

说明

  • 支持本地文件路径和 HTTP(S) URL 两种输入
  • 支持 PDF, DOC, DOCX, PPT, PPTX, PNG, JPG, JPEG, HTML 格式
  • 未指定输出路径时,默认保存到 ./temp/<文件名>.zip
  • 转换完成后自动解压 zip 并读取 Markdown 内容
  • 可附加自然语言指令,让 Claude 对转换结果进行分析、总结或回答问题

API 限制

根据 MinerU API 文档:

  • 单个文件不超过 200MB(PDF 超过此限制会自动拆分)
  • 文件页数不超过 600 页(超过此限制会自动使用 page_ranges)
  • 每账号每天有 2000 页高优先级额度
  • 不支持 GitHub、AWS 等国外 URL(网络限制)

输出格式

转换完成后,会得到一个包含以下内容的 zip 文件:

  • Markdown 文件: 提取的文档内容
  • JSON 文件: 结构化数据
  • 可选格式: 如果指定了 extra_formats,还可能包含 DOCX、HTML、LaTeX 等格式

详细说明请参考:https://opendatalab.github.io/MinerU/reference/output_files/

技术实现

本 MCP 服务器使用 Python requests 库与 MinerU API 交互:

URL 输入流程:
1. 创建任务: POST https://mineru.net/api/v4/extract/task
2. 查询状态: GET https://mineru.net/api/v4/extract/task/{task_id}
3. 下载结果: GET {zip_url} 流式下载到本地

本地文件输入流程:
1. 申请上传链接: POST https://mineru.net/api/v4/file-urls/batch
2. 上传文件: PUT {upload_url} 上传文件内容
3. 系统自动提交解析任务
4. 查询批量结果: GET https://mineru.net/api/v4/extract-results/batch/{batch_id}
5. 下载结果: GET {zip_url} 流式下载到本地

大文件处理流程(>200MB PDF):
1. 智能拆分: 同时考虑大小(180MB)和页数(600页)约束
2. 逐片上传: 每个分片独立上传和处理
3. 分别下载: 每个分片结果独立下载

故障排除

问题:Token 无效

请确保:
1. 从官网正确复制了 Token
2. Token 前后没有空格
3. Token 未过期

问题:解析失败

可能原因:
1. 文件 URL 无法访问
2. 文件格式不支持(请检查是否在支持列表中)
3. 文件为空(0字节)
4. 网络问题(国外 URL)

问题:大文件拆分失败

可能原因:
1. 未安装 PyPDF2(运行 pip install PyPDF2>=3.0.0)
2. 非 PDF 格式的大文件无法自动拆分,需手动缩小

许可证

MIT License

相关链接

  • MinerU 官网
  • MinerU 文档
  • Model Context Protocol

常见问题

8 问
答案由本站依据条目字段整理,不引用上游原文
Miner U MCP 怎么安装?

在客户端按下面的安装命令接入:pip install -r requirements.txt。装完在客户端配置里引用同一个包或端点。

Miner U MCP 怎么在 Claude Desktop、Claude、Cursor 里配置?

它的传输方式是stdio · 本地进程,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

Miner U MCP 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

Miner U MCP 需要 API Key 吗?

资料标注需要API Key认证,使用前准备好对应凭据,并按最小权限配置。

Miner U MCP 支持哪些客户端?

资料标注支持 Claude Desktop、Claude、Cursor;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

Miner U MCP 能提供哪些能力?

资料显示约 4 个工具;能力标签包括 文档转换、Python、Claude、多格式支持。具体工具清单以官方文档为准。

Miner U MCP 需要什么运行环境?

属于本地进程,需要在本机装好运行环境。

Miner U MCP 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-05-17。