AvatarGanymede/MinerU-MCP 安装教程：把 MinerU 文档转 Markdown 接入 MCP

作者：袖梨 2026-07-22

我最近在给 Agent 搭一套“文档直接转 Markdown”的流程，试到 AvatarGanymede/MinerU-MCP 这个仓库时，一看就觉得：它不复杂，但安装路线真的容易选错。我自己主要踩了三个地方：MinerU Token 没放进 MCP 环境变量、TypeScript 版拿去跑本地文件、源码启动时 cwd 写错导致客户端一直连不上。尤其是本地 PDF 路径那块，表面像是文件解析失败，实际是 MCP 启动路径不对，排了十几分钟才绕出来。

AvatarGanymede/MinerU-MCP GitHub 仓库首页截图，文件区显示 .claude skills、src、README.md、package.json、pyproject.toml、requirements.txt 和 render.yaml，右侧说明它是通过 MinerU API 将 PDF、Word、PPT、图片和 HTML 转为 Markdown 的 MCP server

先弄明白它不是普通转换脚本

MinerU-MCP 是一个 Model Context Protocol 服务器，核心能力是调用 MinerU API，把 PDF、Word、PPT、图片、HTML 这类文件转换成 Markdown。它不是那种单独打开的网页工具，也不是只跑一次的命令行脚本，而是装进 Claude Desktop、Cursor、Claude Code 或其他 MCP 客户端后，让 Agent 通过工具调用去完成解析。

仓库 README 里给到的能力比较明确：支持 URL 和本地文件输入，支持 OCR、公式识别、表格识别，还能根据文件类型自动配置模型参数。比较实用的是大 PDF 处理逻辑，超过 200MB 的 PDF 会尝试物理拆分，超过 600 页会使用 page_ranges 分段处理。

这里有个小提醒：如果你只是转在线文件，路线可以轻一点；如果你要处理本地文件、大文件、扫描件，建议直接走 Python 版。别一上来就选 TypeScript 版然后拿本地路径硬试，那个方向会绕。

安装前先准备这些

开始安装前，先把几个基础条件确认好。MinerU-MCP 最关键的是 MINERU_API_KEY，没有这个 Token，MCP 服务能启动也没法真正提交解析任务。

你需要准备：

  • 一个 MinerU 账号，并在 https://mineru.net/apiManage/token 里获取 API Token。
  • Python 3.10 或更高版本，Python 版依赖在 requirements.txt 和 pyproject.toml 里。
  • 如果走 uvx，需要先安装 uv。
  • 如果走 TypeScript 或 Render/Smithery 部署，需要 Node.js 20+。
  • 一个支持 MCP 配置的客户端，比如 Claude Desktop、Cursor、Claude Code 等。

我习惯先把 Token 单独复制到一个临时记事本里，只留纯 Token，不带空格、不带引号。这个动作很土，但能少掉一堆“Token 无效”的假故障。

推荐路线：uvx 直接启动

如果你只是想快速接入 MCP，不想手动维护依赖，仓库推荐的启动方式是 uvx。先在终端里试一下命令能不能跑起来：

uvx mineru-converter-mcp-server stdio

然后把 MCP 配置写进 Claude Desktop 或 Cursor。macOS 的 Claude Desktop 配置文件通常在：

~/Library/Application Support/Claude/claude_desktop_config.json

Windows 常见位置是：

%APPDATA%Claudeclaude_desktop_config.json

推荐使用下面这种模块启动写法。它比直接跑 console script 更稳，仓库里也特别提到，这样可以规避 Windows 下 uvx console script 的兼容问题。

{
  "mcpServers": {
    "mineru": {
      "command": "uvx",
      "args": [
        "--with",
        "mineru-converter-mcp-server",
        "python",
        "-m",
        "mineru_mcp",
        "stdio"
      ],
      "env": {
        "MINERU_API_KEY": "your_mineru_api_token"
      }
    }
  }
}

把 your_mineru_api_token 换成你自己的 MinerU Token。改完后重启 MCP 客户端，让它重新加载配置。别只保存文件就开始测试，客户端不重启时经常读不到新服务。

需要本地文件和大文件，就走 Python 源码版

我更偏向把 Python 版当作“正式使用路线”。原因很简单：它支持本地文件上传，也支持大 PDF 拆分。你要转本地论文、扫描件、PPT、Word，基本都会用到这些能力。

先把仓库 clone 到本地：

git clone https://github.com/AvatarGanymede/MinerU-MCP.git
cd MinerU-MCP

创建并启用虚拟环境。macOS 或 Linux 可以这样：

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Windows 可以这样：

python -m venv .venv
.venvScriptsactivate
pip install -r requirements.txt

源码版的 MCP 配置示例：

{
  "mcpServers": {
    "mineru": {
      "command": "python",
      "args": ["src/mineru_mcp/server.py"],
      "cwd": "C:/path/to/MinerU-MCP",
      "env": {
        "MINERU_API_KEY": "your_mineru_api_token"
      }
    }
  }
}

这里的 cwd 必须换成你本机真实的仓库根目录。macOS 可以写成类似：

"cwd": "/Users/yourname/tools/MinerU-MCP"

我自己就卡过一次 cwd，当时只盯着文件路径看，忘了 MCP 进程是从配置里的工作目录启动的。报错信息不够直白，排起来确实有点烦。

TypeScript 版适合远程部署，不适合本地文件

这个仓库也提供 TypeScript 版，适合 Smithery、Render 或本地 HTTP 服务这类场景。准备 Node.js 20+ 后，在项目根目录安装依赖：

npm install

macOS 或 Linux 的 MCP 配置可以这样写：

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

Windows 下通常需要通过 cmd /c 调用：

{
  "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

或者直接指定 Token：

MINERU_API_KEY=xxx npx tsx src/server-http.ts

默认端口是 10000，会暴露 /mcp 和 /.well-known/mcp-config。这个路线更偏部署和分发，不是本地文档批量处理的首选。

AvatarGanymede/MinerU-MCP 仓库 .claude/skills/convert-to-markdown/SKILL.md 页面截图，内容说明 convert-to-markdown skill 支持 URL 和本地文件路径，并以 convert_to_markdown 作为默认转换工具

装好后先跑一个小验证

不要一上来就丢几百页 PDF。先找一个体积小、内容正常的 PDF 或 Word 文件，验证 MCP 能不能被客户端识别、能不能提交任务、能不能下载结果。

在 Agent 里可以这样测试：

请使用 MinerU MCP 的 convert_to_markdown 工具，把这个本地文件转成 Markdown：
url: C:/Documents/test.pdf
output_path: C:/output/mineru-test.zip

如果你使用仓库自带的 Claude Code skill，也可以直接用斜杠命令：

/convert-to-markdown C:/Documents/test.pdf 提取这份文档的章节标题和表格内容

正常情况下，流程会经历提交任务、轮询状态、下载 zip、读取 Markdown。输出 zip 里通常会有 Markdown 文件和 JSON 结构化数据；如果额外指定格式，也可能包含 DOCX、HTML、LaTeX 等内容。

我会额外加的本地自检脚本

仓库 README 已经把安装命令写清楚了，但实操时我还是建议加一个简单自检。它不调用 MinerU API，只检查 Token、Python 版本、依赖和待转换文件路径，能提前挡掉很多低级错误。

# save as mineru_local_check.py
import os
import sys
from pathlib import Path

SUPPORTED = {".pdf", ".doc", ".docx", ".ppt", ".pptx", ".png", ".jpg", ".jpeg", ".html"}

def check_file(path_text: str) -> None:
    path = Path(path_text).expanduser()
    if not path.exists():
        raise SystemExit(f"file not found: {path}")
    if path.suffix.lower() not in SUPPORTED:
        raise SystemExit(f"unsupported file type: {path.suffix}")
    print(f"file ok: {path}")

def main() -> None:
    key = os.getenv("MINERU_API_KEY", "").strip()
    print("python:", sys.version.split()[0])
    print("MINERU_API_KEY:", "ok" if key else "missing")

    try:
        import requests
        import PyPDF2
        import docx
        import pptx
    except Exception as exc:
        raise SystemExit(f"dependency missing: {exc}")

    if len(sys.argv) > 1:
        check_file(sys.argv[1])

if __name__ == "__main__":
    main()

运行方式：

python mineru_local_check.py /path/to/test.pdf

这个脚本适合放在源码版目录里，批量转换前跑一下。尤其是中文路径、空格路径、PPTX 后缀写错这种小问题，提前发现会舒服很多。

常见故障排查表

现象 可能原因 处理办法
MCP 服务能看到，但调用时报 Token 无效 MINERU_API_KEY 没配置、复制时带了空格，或者 Token 已过期。 重新从 MinerU Token 页面复制，放到 MCP 配置的 env 里，保存后重启客户端。
本地 PDF 一直解析失败 用了 TypeScript 版，或者源码版 cwd 不在仓库根目录。 本地文件改用 Python 版；检查 cwd 是否指向 MinerU-MCP 根目录。
在线 URL 解析失败 文件 URL 无法公开访问，或遇到 GitHub、AWS 等国外 URL 网络限制。 把文件下载到本地后用 Python 版上传解析。这里不要硬拗，能本地走就本地走。
大文件拆分失败 缺少 PyPDF2，或者文件不是 PDF，大文件不能自动拆分。 安装依赖：pip install -r requirements.txt；非 PDF 大文件建议手动压缩或拆分。
Windows 上 uvx 启动不稳定 console script 兼容问题。 按仓库推荐使用 python -m mineru_mcp stdio 的模块启动写法。
转换一直等待，没有结果 文档较大，默认等待时间不够，或者网络到 MinerU API 不稳定。 把 max_wait_seconds 调大，比如 600；同时先用小文件确认基础链路正常。

多 MCP 共存时这样减少误调用

如果你的客户端里已经装了好几个 PDF 转 Markdown、OCR、文档解析类 MCP，建议把这个服务名保持成 mineru，不要改成 doc、parser 这种泛名。工具多了以后，名字越含糊，Agent 越容易选错。

我自己的提示词会直接写清楚：

请优先使用 mineru 这个 MCP 服务处理文档解析。
如果是本地文件，请使用 Python 版 MinerU-MCP 的 convert_to_markdown。
不要调用其他 OCR 或 PDF-to-Markdown 工具。

这几句看起来有点啰嗦，但批量处理文档时很有用。尤其是同一个客户端里还有别的 OCR 服务时，少写一句，结果可能就跑偏。

批量转换指令模板

MinerU-MCP 的推荐工具是 convert_to_markdown，它会自动完成提交、轮询、下载。批量转换时，我建议不要让 Agent 自己猜输出目录，直接把文件清单和输出路径写死。

请使用 mineru MCP 的 convert_to_markdown 工具批量转换下面 4 个文件。

统一要求：
- 每个文件单独输出一个 zip
- 输出目录统一放到 C:/output/mineru-md/
- 转换完成后读取每个 zip 里的 Markdown
- 给我汇总每份文档的标题、核心结论、表格信息
- 如果某个文件失败，继续处理下一个，并把失败原因列出来

文件清单：
1. C:/Documents/report-01.pdf
2. C:/Documents/product-plan.docx
3. C:/Documents/demo-slides.pptx
4. C:/Documents/scan-page.png

这个模板的重点是“失败继续处理下一个”。不然一个文件卡住，后面的任务全停，等你回来看时会有点崩。

什么时候选 Render 或 Smithery

如果你只是自己电脑上用，没必要一开始就部署。源码版或 uvx 就够了。Render 和 Smithery 更适合团队分发、远程 MCP、统一入口这类场景。

仓库里已经带了 render.yaml，Render 会读取它来启动服务。单租户自用可以在 Render 环境变量里设置 MINERU_API_KEY；如果是 Smithery Deploy via URL，仓库说明里建议不要在服务端固定 Token，而是让每个用户自己填 mineruApiKey。这个边界要分清，不然后面密钥管理会乱。

安装完成后的收尾确认

到这里，整套安装流程基本就走完了。我平时会快速核对几个关键节点：MinerU Token 已经写进 MCP 环境变量，客户端里能看到 mineru 服务，convert_to_markdown 能跑通一个小文件，输出 zip 里能找到 Markdown，本地文件场景使用的是 Python 版，大文件任务已经把等待时间调够。

这些都没问题，就说明 AvatarGanymede/MinerU-MCP 已经可以稳定投入使用。后面真正用它处理资料时，记得先判断输入来源：在线 URL 可以轻量走，涉及本地文件、PPT、扫描件和大 PDF，直接用 Python 版，少走弯路。

相关文章

精彩推荐