---

✨ v4.0.0 亮点（2026-05-16）

• 🚀 覆盖官方完整能力：精准 API（/api/v4/）+ Agent 轻量 API（/api/v1/agent/）双线
• 🔥 6 个 MCP 工具：process_document / process_directory / process_document_lite / query_task_status / renew_tokens / get_token_status
• 🛡️ 健壮性大幅升级：30+ 错误码分类、智能重试、Token 自动续期、URL 服务端直传（无需下载）
• 📐 服务端 200 页限制适配：自动拆分 180 页/片处理后合并；无缝处理 1000+ 页文档
• 🐛 修复严重 bug：图片引用路径错位（影响所有历史输出，v4.0.0 已彻底解决）
• 🧪 测试体系：30 unit + 31 integration + 24 regression + 2 e2e = 87 tests, 100% pass

详见 docs/CHANGELOG.md 和 docs/API_V4_REFERENCE.md。

---

🏗️ 架构

5 层 / 10 模块 / 6 个 MCP 工具 / 双 API 客户端 — 一图看懂：

层	模块	职责
① MCP 接入层	mineru_mcp_server.py	6 个 MCP 工具的 schema + 调度
② 协调编排层	auto_split.py / mineru_batch_async.py / mineru_async.py / progress.py	拆分→处理→合并的本地协调（无网）
③ API 客户端层	MinerUAsyncClient / AgentAPIClient	调 MinerU 服务端的两套 API
④ 基础设施	api_errors.py / token_manager.py / path_fixer.py / split_large_file.py	错误处理、Token 管理、路径修复、PDF 物理拆分
⑤ 外部依赖	MinerU 服务端 / batch_login.py / all_tokens.json	6 个账号配额 6000 页/天

---

🔄 处理流程

输入 → 验证 → 拆分判断 → 提交 → 错误处理 → 轮询 → 下载 → 合并 → Markdown 输出：

关键能力：

• URL 优先服务端直传（不下载到本地），失败兜底走下载-上传
• 图片自动开 OCR，HTML 自动切 MinerU-HTML 模型，Office 自动切 pipeline
• 30+ 错误码分类：RETRYABLE / AUTH / QUOTA / PERMANENT，分别配重试策略
• path_fixer 修复 v3.x 严重 bug：images/x.jpg → {stem}_images/x.jpg，593 张图片缺失 0

---

🔪 自动拆分协调流程

服务端硬限制 200 页 / 200 MB。超规格文件全自动拆分→并发处理→智能合并，对调用方完全透明：

真实案例：某 496 页 PDF → 自动拆 3 片（166+166+164）→ 3 片同时处理 → 合并为单 .md ~210 K 字符。总耗时 ~3 分钟（vs 串行单线程预估 ~9 分钟）。

---

🛠️ MCP 工具

6 个 MCP 工具 · 决策树：

#	工具	用途	关键参数
1	process_document	精准 API 单文件处理	11 参数（含 language / is_ocr / page_ranges / extra_formats / data_id 等）
2	process_directory	精准 API 批量并行	10 参数 + max_workers
3	process_document_lite	Agent 轻量 API（≤10MB / 20 页 / 免 Token）	6 参数
4	query_task_status	异步查询任务进度	task_id, lite
5	get_token_status	Token 状态报告	—
6	renew_tokens	触发 Token 自动续期	force, headless

完整参数参考：docs/API_V4_REFERENCE.md

---

📊 性能与实测

真实数据（5 个文档 1229 页混合 PDF 集合）

文件	页数	处理方式	MD 字符	图片	缺失
PDF-A	91	直接处理	48,117	23	0
PDF-B	143	直接处理	82,443	1	0
PDF-C	190	直接处理	243,271	519	0
PDF-D	309	自动拆 2 片	247,435	30	0
PDF-E	496	自动拆 3 片	209,471	0	0
合计	1,229	—	830,737	573	0

总耗时（含 OCR 全部 5 个文件）：约 10 分钟。

异步并发性能对比

场景	串行处理	v4 并发处理	提升
单文件	23 秒	23 秒	—
3 文件	149 秒	88 秒	1.7×
10 文件	300 秒	30 秒	10×

OCR 收益分布（A/B 实测）

PDF	异体字（无 OCR）	异体字（有 OCR）	OCR 收益
PDF-A	5,063	0	🟢 巨大（GBK 字体异体字 → 标准中文）
其他 4 本	0	0	🟡 微小（PDF 已用标准字体）

结论：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  # 填入账号信息

批量登录获取 Token（默认 headless）

.venv/bin/python3 src/batch_login.py

脚本会自动：访问登录页 → 填账号密码 → 自动通过阿里云验证码 → 保存 Token 到 all_tokens.json。Token 有效期约 90 天。

使用

方式 1: MCP 工具（推荐，在 Kiro CLI / Claude Desktop 中）

"帮我处理 ~/Documents/report.pdf"
"处理 ~/Documents 目录下所有 PDF"
"查看 MinerU 的 Token 状态"

方式 2: 命令行批量

# 批量异步并行
.venv/bin/python3 src/mineru_batch_async.py ~/Documents '*.pdf'

---

📦 安装

系统要求

• Python 3.10+
• uv（Python 包管理器）
• Git

手动安装

# 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 冲突。

MCP 服务器配置

编辑 ~/.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"
      }
    }
  }
}

Kiro Skill 安装（可选）

cp -r skills/mineru-token-manager ~/.kiro/skills/

安装后，AI 助手会自动：处理文档前检查 Token 是否过期 → 过期时自动触发 headless 续期 → 续期完成继续处理。

---

🧪 测试

测试体系

类型	数量	用时	说明
unit	30	0.4s	毫秒级、无依赖
integration	31	0.4s	不调真网，用 tmp/mock
regression	24	0.6s	防已修 bug 复发
e2e	2	~30s	真调 MinerU API
合计	87	—	100% 通过

运行方式

# 默认（不调网络）
.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。

---

🔧 技术栈

技术	版本	用途
niquests	3.10+	HTTP/2+HTTP/3 异步客户端
MCP SDK	1.0+	Model Context Protocol
Rich	13.0+	终端 UI
PyPDF2	3.0+	PDF 解析 + 物理拆分
Playwright	1.40+	自动登录（headless）
pytest	8.0+	测试框架

---

📁 项目结构

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！

提交前请确保：

1. uv pip install -r requirements-dev.txt
2. .venv/bin/python3 -m pytest 全过
3. 涉及 bug 修复时新增 regression 测试

---

📄 许可证

MIT License

---

🙏 致谢

• MinerU — 提供强大的文档解析 API
• Anthropic — Model Context Protocol
• niquests — 现代 HTTP 客户端

---