MinerU MCP

English · Español

MinerU MCP — 通过 Model Context Protocol (MCP) 为 AI Agent 提取和解析 PDF

将任意 PDF 文档转换为结构化 Markdown、表格和 LaTeX 代码，供你的 AI Agent 使用。 开源 MCP 服务，通过 Model Context Protocol 向 Claude Code、Cursor、Windsurf、Hermes Gateway 及任何兼容客户端提供 MinerU（PDF-Extract-Kit / MinerU2.5-VLM）的提取能力。FastMCP HTTP/SSE + 支持本地路径或 Base64，客户端零依赖，100% 使用你的硬件。

标签： mcp-server · mineru · pdf-parser · ocr · latex · ai-agents · fastmcp · claude-code · cursor · hermes-gateway · local-first · self-hosted

_{Agent 通过 MCP 发送 PDF，并收到包含 LaTeX 方程和表格的 Markdown——MinerU 在你的服务端运行，客户端无需安装 PyTorch。此演示使用真实的 mineru-api，通过 scripts/demo_parse.py 录制。}

---

💡 为什么要开发

从 PDF 文件中提取结构化文本、复杂表格和数学公式，通常需要在每台客户端机器上安装包含 PyTorch、OCR 和视觉模型的庞大 Python 环境。MinerU MCP 通过充当解耦的 HTTP/SSE 中间件适配器解决了这一问题：

• 🚀 无需本地安装：任何 MCP 客户端都可以通过 HTTP/SSE 在端口 8202 处理文档，只需传入本地 file_path 或发送以 file_base64 编码的 PDF。
• 📊 结构化 Markdown 和 LaTeX：将标题、列表、复杂表格和数学公式转换为标准 LaTeX 代码，可直接用于 RAG。
• 🧠 共享 GPU，无需争抢：pipeline（默认）需要约 1.5 GB VRAM；hybrid-engine 和 vlm-engine 需要约 4 GB，精度更高。如果主机有 GPU Broker，每次解析都会先申请 VRAM，并在完成后归还，因此可以与本地 LLM 共用同一块显卡。

---

⚡ 快速入门

mineru-mcp 只是 MCP 层：你需要运行中的 mineru-api（mineru==3.4.4）。主机部署方法：docs/SERVER_SETUP.md。

有两种运行方式，任选一种：

模式	适用场景	启动方式
HTTP	在运行 mineru-api 的机器上启动一个服务，供网络中的所有客户端共享（主要用法）	手动启动（或通过服务启动），并保持监听 http://<server>:8202/mcp。
stdio	客户端与 mineru-api 运行在同一台机器上	客户端自行启动进程（uvx 或 Docker）。不会开放端口。

要求：uv ≥ 0.13.4（或 pip ≥ 26.2.2）；更早版本仍信任已泄露的 emSign CA（GHSA-6q48-6c7w-9gw2）。uv pip install -e . 会自动检查（pyproject.toml 中的 [tool.uv] required-version）；uvx --from git+… 不会，因为它在项目外运行：请检查 uv --version。

选项 A — HTTP（共享服务）

git clone https://github.com/GermaniU/mineru-mcp.git
cd mineru-mcp
uv venv && source .venv/bin/activate
uv pip install -e .
MINERU_URL=http://127.0.0.1:8000 mineru-mcp

MCP 端点：http://<server>:8202/mcp。将其粘贴到客户端配置中（参见 docs/CLIENTS.md — Claude Code、Cursor、Continue、OpenCode、Hermes Gateway）。

选项 B — 使用 Docker 的 stdio

镜像 ghcr.io/germaniu/mineru-mcp 通过 stdio 使用 MCP，并调用运行在主机上的 mineru-api。在 MCP 客户端中进行配置：

{
  "mcpServers": {
    "mineru": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--add-host", "host.docker.internal:host-gateway",
        "-e", "MINERU_URL=http://host.docker.internal:8000",
        "ghcr.io/germaniu/mineru-mcp:latest", "--stdio"
      ]
    }
  }
}

在容器内，file_path 指的是容器的文件系统：通过 file_base64 + file_name 发送文档，或使用 -v 挂载目录。容器内没有 systemd，因此没有按需唤醒或 GPU Broker：mineru-api 必须已在运行。

不使用 Docker：uvx --from git+https://github.com/GermaniU/mineru-mcp mineru-mcp --stdio，需要 uv ≥ 0.13.4（配置见 docs/CLIENTS.md）。

🔍 诊断

mineru_health 会显示 mineru-api 是否有响应、其版本和排队中的任务，并区分休眠（因不活跃而停止）和故障的后端。无需 MCP 客户端即可调用，可使用 curl 冒烟测试。

---

⚙️ 配置（环境变量）

创建 .env 文件或导出以下变量：

变量	默认值	描述
MINERU_URL	http://127.0.0.1:8000	mineru-api 的 URL。只接受 loopback 和 host.docker.internal；使用任何其他主机时，工具都会拒绝发送文档。
MINERU_BACKEND	pipeline	调用未指定时使用的后端（pipeline、hybrid-engine、vlm-engine）。
MINERU_PARSE_METHOD	auto	调用未指定时使用的提取方法（auto、txt、ocr）。
MINERU_LANG	es	调用未指定时使用的 OCR 语言。
MINERU_SYSTEMCTL_SCOPE	user	mineru-api 的 unit 所在位置，用于唤醒服务和查询状态：user（systemctl --user）或 system（/etc/systemd/system）。其他值会阻止服务启动。
MCP_HOST	0.0.0.0	HTTP 模式的主机绑定地址。
MCP_PORT	8202	HTTP 模式的端口。
MCP_AUTH_TOKEN	(空 = 无身份验证)	如果设置，HTTP 模式会要求每个请求都包含 Authorization: Bearer <token>。
MCP_TRANSPORT	(空 = HTTP)	stdio 等同于传入 --stdio。

各项设置分别提供什么保护、不提供什么保护：SECURITY.md。

---

🛠️ 暴露的工具（工具参考）

工具	功能
parse_document	将 PDF、DOCX、PPTX、XLSX 或图像同步解析（30-120 秒）为 Markdown。输入：file_path（服务上的路径）或 file_base64 + file_name。可选参数：backend、effort、image_analysis、parse_method、lang、formula_enable、table_enable、start_page、end_page。
submit_parse_task	与 parse_document 相同，但以异步方式运行：返回一个 task_id。适用于超过约 50 页的文档。
get_task_status	任务状态（pending / processing / completed / failed）。
get_task_result	已完成任务的 Markdown。
mineru_health	mineru-api 的可用性、版本和排队中的任务。

start_page 和 end_page 从 0 开始计数：示例会请求 start_page: 4, end_page: 5，并获取论文的第 5 和第 6 页。hybrid-engine + effort=high + image_analysis=true 会将图形转换为 Mermaid 图表。

---

🎯 当前范围

MinerU MCP 刻意保持轻量。它只做一件事：将文档从 MCP 客户端传送到你的 mineru-api，并返回 Markdown。解析由 MinerU 完成。

做什么

• ✅ 将 PDF、DOCX、PPTX、XLSX、PNG 和 JPG 转换为 Markdown，并保留标题、表格（HTML）和公式（LaTeX）。
• ✅ 接收来自其他机器的文档：可以是服务上的路径（file_path），也可以是文件内容（file_base64 + file_name）。
• ✅ 短文档同步解析；长文档异步解析，返回 task_id，并支持指定页码范围。
• ✅ 如果 mineru-api 已停止且系统使用 systemd，则启动服务（systemctl --user start；设置 MINERU_SYSTEMCTL_SCOPE=system 时不加 --user），并等待服务就绪后再解析。
• ✅ 如果主机配有 GPU Broker，则向其申请 VRAM，并在完成后归还。

目前还不能做的事

• ❌ 不包含 mineru-api 和模型。 它们需要在主机上单独安装并配置服务：docs/SERVER_SETUP.md。
• ❌ 不会将文档发送到你的网络之外。 如果 MINERU_URL 不是回环地址，就会拒绝发送文档；不会使用 MinerU 的云端 API。
• ❌ 不会返回提取出的图片，只返回 Markdown。
• ❌ 长文档提取不会以流式方式逐步返回 Markdown：会使用 submit_parse_task 并查询任务状态。
• ❌ 不会保存文档或结果。 Base64 文件的临时文件会在处理结束后删除。
• ❌ **Docker 中不支持按需唤醒或 GPU Broker：**必须先启动 mineru-api。

如果你需要上述暂不支持的功能，请提交一个 issue，并附上实际用例。

---

🧭 其他文档 MCP 服务有哪些？

它们分为三类，解决的问题各不相同。

	MinerU MCP（本项目）	MinerU 官方 MCP（云端）	通用转换器（Docling、MarkItDown）
解析位置	你的 mineru-api，运行在你的硬件上	MinerU 的云端 API	运行 MCP 的机器
文档是否会离开你的网络	不会（会拦截外部 URL）	会	不会
账号 / 令牌	无需	MinerU API 令牌	无需
客户端依赖	无（HTTP）或仅需 Docker（stdio）	Python（uvx mineru-open-mcp）	完整的转换引擎
是否与本地大模型共享 GPU	是（GPU Broker）	不适用	否
引擎	MinerU（pipeline / vlm / hybrid）	MinerU	各自的引擎

一句话概括：

• 如果你没有 GPU 或服务器，也不介意上传文档 → 使用 MinerU 官方云端 MCP。
• 如果你想在与客户端相同的机器上运行转换器 → 使用 Docling 或 MarkItDown。
• 如果你已经在自己的服务器上运行 MinerU（或打算这样做），并希望文档不离开你的网络，供 LAN 内所有客户端共享 → 使用本项目。

---

🔌 连接客户端

可直接复制的配置见 docs/CLIENTS.md（HTTP 和 stdio）：

• 🟦 Claude Code — claude mcp add -s user -t http mineru http://<server>:8202/mcp（工具会在新会话中显示）。
• 🟧 Cursor — Settings → MCP Servers → Add new MCP Server。
• 🟩 Continue（VS Code / JetBrains）— ~/.continue/config.json。
• 🟪 OpenCode — ~/.config/opencode/config.json。
• 🟨 Hermes Gateway — ~/.hermes/config.yaml 中的 mcp_servers。
• 🟫 Claude Desktop — 在运行 mineru-api 的机器上通过 uvx 或 Docker 使用 stdio。

可直接使用的代码片段见 examples/。

---

🧪 使用 curl 进行冒烟测试

HTTP 模式为无状态：只需一个请求，无需 initialize 或 mcp-session-id。

curl -sS -X POST http://localhost:8202/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"mineru_health","arguments":{}}}'

设置了 MCP_AUTH_TOKEN 时，添加 -H "Authorization: Bearer <token>"。

如需完整测试（健康检查 + 真实解析 arXiv 论文的两页），请运行 GIF 演示中的命令：

MCP_DEMO_URL=http://localhost:8202/mcp python scripts/demo_parse.py

---

🧱 架构

⚠️ 系统边界：mineru-mcp 仅负责 MCP 传输与接口层。它不包含处理引擎 mineru-api，也不负责从 HuggingFace 缓存下载模型。

 +-------------------------------------------------------+
 |                 Clientes MCP (LAN)                    |
 | (Claude Code CLI / Cursor / Windsurf / Hermes Gateway)|
 +-------------------------------------------------------+
                             |
                             | HTTP / SSE (Puerto 8202)
                             v
 +-------------------------------------------------------+
 |                   mineru-mcp Server                   |
 |        (FastMCP + File Path / Base64 Decoder)         |
 +-------------------------------------------------------+
                             |
                             | Loopback HTTP (Puerto 8000)
                             v
 +-------------------------------------------------------+
 |                  MinerU Backend Host                  |
 |  (mineru-api + PDF-Extract-Kit + HuggingFace Cache)   |
 +-------------------------------------------------------+

每个工具都位于 src/mineru_mcp/tools/；server.py 只负责在 FastMCP 中注册工具并启动传输层。技术详情见 docs/ARCHITECTURE.md。

---

🤝 参与贡献

欢迎提交 PR、issues 和 forks（MIT）。

规则（摘要）：

1. 改动小而直接。 修改能够解决问题的最小代码路径。
2. 不要引入推测性抽象或不必要的新依赖。
3. **保留工具的名称和参数：**客户端依赖这些内容。
4. 标识符使用英语，注释和提交信息使用西班牙语。遵循 Conventional Commits（feat:、fix:、docs:、refactor:、test:、chore:）。

完整详情见 CONTRIBUTING.md。

uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"
pytest          # unit tests, sin mineru-api
ruff check .

---

🩹 故障排除

mineru_health 返回 MinerU no disponible (el backend está inactivo)

• mineru-api 已停止（例如，被用于释放 VRAM 的空闲看门狗停止）。这不是错误：parse_document 或 submit_parse_task 会启动它。

BLOQUEADO por seguridad: MINERU_URL apunta a …

• MINERU_URL 既不是 loopback 地址，也不是 host.docker.internal。这是有意为之：文档不会离开你的机器。参见 SECURITY.md。

MinerU no respondió tras 90s de arrancarlo 或后端已启动但 mineru_health 显示 inactivo

• scope 与 unit 不匹配：MINERU_SYSTEMCTL_SCOPE=user 会查找 ~/.config/systemd/user/mineru-api.service，而 system 会查找 /etc/systemd/system/mineru-api.service。使用 user 时，MCP 必须在同一用户的 systemd 会话中运行（例如，作为用户 unit 运行）。参见 docs/SERVER_SETUP.md。

MinerU no responde en … y aquí no hay systemd para arrancarlo

• 你在 Docker 或 macOS 中运行：无法唤醒 mineru-api。请手动启动后重试。

使用 curl 请求 endpoint 时出现 406 Not Acceptable

• 缺少 header Accept: application/json, text/event-stream。

401 {"error":"unauthorized"}

• 服务设置了 MCP_AUTH_TOKEN：请发送 Authorization: Bearer <token>。

Error: timeout. El documento puede ser muy grande

• 使用 submit_parse_task 并通过 get_task_status 查询，或使用 start_page / end_page 按范围解析。

---

📚 文档

• docs/SERVER_SETUP.md — 在主机上安装 mineru-api、模型和服务。
• docs/CLIENTS.md — Claude Code、Cursor、Continue、OpenCode、Hermes Gateway 和 Claude Desktop 的配置。
• docs/ARCHITECTURE.md — 组件、请求流程和 GPU Arbiter。
• SECURITY.md — 威胁模型和漏洞报告方式。
• CONTRIBUTING.md — 开发环境、代码风格规则和工作流。
• CHANGELOG.md — 变更历史。

---

📄 许可证

MIT — 随意使用、fork 并改进。

---

由 @GermaniU 制作。 如果对你有帮助，请点一颗 ⭐，让更多人发现它。如果遇到问题，请提交 issue，我们会修复。