MinerU MCP Server
完整的 MinerU 文档处理解决方案 — v4.0.0 全面升级版
精准 API + Agent 轻量 API · 全参数透传 · 智能错误重试 · 自动拆分合并 · Token 自动续期
接入你的智能体
從發布者安裝。不是 PlugMCP 端點。
遠端 URL 還是本機指令? 兩種安裝方式的差異
/api/v4/)+ Agent 轻量 API(/api/v1/agent/)双线process_document / process_directory / process_document_lite /
query_task_status / renew_tokens / get_token_status5 层 / 10 模块 / 6 个 MCP 工具 / 双 API 客户端 — 一图看懂:
输入 → 验证 → 拆分判断 → 提交 → 错误处理 → 轮询 → 下载 → 合并 → Markdown 输出: 关键能力:
MinerU-HTML 模型,Office 自动切 pipelineimages/x.jpg → {stem}_images/x.jpg,593 张图片缺失 0服务端硬限制 200 页 / 200 MB。超规格文件全自动拆分→并发处理→智能合并,对调用方完全透明: 真实案例:某 496 页 PDF → 自动拆 3 片(166+166+164)→ 3 片同时处理 → 合并为单 .md ~210 K 字符。总耗时 ~3 分钟(vs 串行单线程预估 ~9 分钟)。
6 个 MCP 工具 · 决策树:
完整参数参考:docs/API_V4_REFERENCE.md
总耗时(含 OCR 全部 5 个文件):约 10 分钟。
结论:OCR 对 GBK 古籍 PDF 收益巨大;对标准 Unicode PDF 收益不显著。process_document 默认 is_ocr=False,扫描型 PDF 显式传 is_ocr=True 即可。
git clone https://github.com/neosun100/mineru-mcp-server.git
cd mineru-mcp-server
./install_mcp.sh
cp config/accounts.yaml.example config/accounts.yaml
vi config/accounts.yaml # 填入账号信息
.venv/bin/python3 src/batch_login.py
脚本会自动:访问登录页 → 填账号密码 → 自动通过阿里云验证码 → 保存 Token 到 all_tokens.json。Token 有效期约 90 天。
"帮我处理 ~/Documents/report.pdf"
"处理 ~/Documents 目录下所有 PDF"
"查看 MinerU 的 Token 状态"
# 批量异步并行
.venv/bin/python3 src/mineru_batch_async.py ~/Documents '*.pdf'
# 1. 克隆仓库
git clone https://github.com/neosun100/mineru-mcp-server.git
cd mineru-mcp-server
# 2. 创建虚拟环境(必须用 uv,避免环境冲突)
uv venv
source .venv/bin/activate
# 3. 安装运行时依赖(必须用 uv pip)
uv pip install -r requirements.txt
.venv/bin/playwright install chromium
# 4. 安装开发依赖(可选,跑测试时需要)
uv pip install -r requirements-dev.txt
# 5. 配置账户
cp config/accounts.yaml.example config/accounts.yaml
vi config/accounts.yaml
# 6. 批量登录
.venv/bin/python3 src/batch_login.py
⚠️ 重要:所有 Python 包安装必须使用
uv pip install,不要用裸pip install。 uv 严格隔离虚拟环境,避免与系统 Python 冲突。
编辑 ~/.kiro/settings/mcp.json(或 Claude Desktop 配置):
{
"mcpServers": {
"mineru": {
"command": "/path/to/mineru-mcp-server/.venv/bin/python3",
"args": ["/path/to/mineru-mcp-server/src/mineru_mcp_server.py"],
"env": {
"PYTHONPATH": "/path/to/mineru-mcp-server/src"
}
}
}
}
cp -r skills/mineru-token-manager ~/.kiro/skills/
安装后,AI 助手会自动:处理文档前检查 Token 是否过期 → 过期时自动触发 headless 续期 → 续期完成继续处理。
# 默认(不调网络)
.venv/bin/python3 -m pytest
# 全量含 e2e(真调 API)
RUN_E2E=1 .venv/bin/python3 -m pytest
# 按 marker
.venv/bin/python3 -m pytest -m unit
.venv/bin/python3 -m pytest -m regression
详见 tests/README.md。
mineru-mcp-server/
├── src/ # 核心代码(10 个模块)
│ ├── mineru_mcp_server.py # ① MCP 接入层
│ ├── auto_split.py # ② 拆分协调
│ ├── mineru_batch_async.py # ② 批量协调
│ ├── mineru_async.py # ② 单文件协调 + ③ 精准 API 客户端
│ ├── agent_api.py # ③ Agent 轻量 API 客户端
│ ├── progress.py # ② 进度回调
│ ├── api_errors.py # ④ 错误码表 + 重试策略
│ ├── token_manager.py # ④ Token 管理
│ ├── path_fixer.py # ④ Markdown 路径修复
│ ├── split_large_file.py # ④ PDF 物理拆分
│ └── batch_login.py # ⑤ headless 自动登录
│
├── tests/ # 87 个测试
│ ├── unit/ # 30 单元测试
│ ├── integration/ # 31 集成测试
│ ├── regression/ # 24 回归测试(防 bug 复发)
│ ├── e2e/ # 2 端到端测试(真调 API)
│ └── README.md # 测试运行手册
│
├── docs/ # 完整文档
│ ├── CHANGELOG.md # 详细变更日志
│ ├── API_V4_REFERENCE.md # 官方 API 参数完整参考
│ ├── images/ # 4 张架构 / 流程图
│ └── ...
│
├── config/
│ └── accounts.yaml.example # 账号配置模板
│
├── skills/
│ └── mineru-token-manager/ # Kiro Skill
│
├── requirements.txt # 运行时依赖
├── requirements-dev.txt # 开发依赖
├── install_mcp.sh # 一键安装脚本
└── README.md # 本文档
docs/CHANGELOG.md — 详细变更日志(v4.0.0 全部修改)docs/API_V4_REFERENCE.md — 官方 API 完整参数参考tests/README.md — 测试运行手册docs/PROCESSING_FLOW.md / docs/MCP_DESIGN.md欢迎提交 Issue 和 Pull Request!
提交前请确保:
uv pip install -r requirements-dev.txt.venv/bin/python3 -m pytest 全过MIT License
⭐ 如果对你有帮助,请给个 Star!
GitHub · Made with ❤️ by neosun100
MinerU MCP Server - 完整的文档处理解决方案。支持PDF/PPTX/DOCX/图片,真正异步并发,批量异步并行,MCP自然语言交互,性能提升10倍。
工具
尚無工具清單。遠端伺服器會在首次健康檢查後取得工具清單。
常見問題
在本頁複製適用於 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 設定。它使用發布者的安裝方式,而不是 PlugMCP 代理伺服器。
這筆記錄未列出必要的環境變數。
Mineru 透過 stdio 在本機執行。
上次檢查時間:2026-11-05。 MinerU MCP Server - 完整的文档处理解决方案。支持PDF/PPTX/DOCX/图片,真正异步并发,批量异步并行,MCP自然语言交互,性能提升10倍。