MinerU MCP Server
完整的 MinerU 文档处理解决方案 — v4.0.0 全面升级版
精准 API + Agent 轻量 API · 全参数透传 · 智能错误重试 · 自动拆分合并 · Token 自动续期
Potencia tu agente
Instalación del publicador. No es un endpoint de PlugMCP.
Host a copy with our keys and logs.
Aún no hay una versión empaquetada en el registro. Sigue el README del repositorio.
¿URL remota o un comando en tu máquina? En qué se diferencian las dos instalaciones
Ejecutar en PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
Abrir/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倍。
Herramientas
Aún no hay lista de herramientas. Los servidores remotos la reciben tras la primera comprobación de estado.
Preguntas frecuentes
Copia en esta página la configuración stdio para Cursor, Claude Desktop, Claude Code o VS Code. Usa la instalación del publicador, no un proxy de PlugMCP.
Este registro no indica ninguna variable de entorno obligatoria.
Mineru se ejecuta localmente por stdio.
Última comprobación: 2026-11-05. MinerU MCP Server - 完整的文档处理解决方案。支持PDF/PPTX/DOCX/图片,真正异步并发,批量异步并行,MCP自然语言交互,性能提升10倍。