Smithery is now a part of Arcade.dev! Read more in our announcement here
Deploy and drive the MinerU document-parsing MCP server to extract markdown + images from PDF / DOCX / PPT / XLS / images via either the cloud (mineru.net, needs token) or a self-hosted server...
把 MinerU 文档解析封装成一个自包含的标准 MCP server，对外暴露为 MCP 工具， 任何 MCP 客户端 (Claude Code / Cursor / 自研客户端) 都可直接连接调用。
本 Skill 包内已附带可运行源码 scripts/mineru_mcp_server.py，按下方步骤即可拉起服务。
MINERU_MODE 决定)| 模式 | 地址 | 协议 | 鉴权 |
|---|---|---|---|
cloud |
线上 mineru.net | POST /file-urls/batch → PUT 上传 → 轮询 /extract-results/batch/{id} → 下载 zip |
需要 apiToken |
server |
本地/自建 (默认 http://172.19.52.100:8006) |
multipart POST /tasks → 轮询 /tasks/{id} → GET /tasks/{id}/result (zip) |
无鉴权 |
parse_document — 解析 PDF/DOCX/PPT/XLS/图片等，返回 markdown 正文(超长截断) + 产物落盘路径。health_check — 探活后端连通性 / 鉴权 (不发起重解析任务)。mcp — 官方 MCP Python SDK，内含 FastMCP (核心，必须)requests — HTTP 客户端pydantic — mcp 内部依赖，装 mcp 会自动带上源码原本从
.env/ 环境变量读取下列值。为方便开箱即用，此处把默认值直接写死； 仅MINERU_API_TOKEN（云端密钥）需替换为你的真实值。把以下内容存为.env或直接export即可。 CLI 参数优先级高于环境变量。
# ===== MinerU MCP 配置 (直接使用，secrets 处替换占位符) =====
# 运行模式: cloud(线上 mineru.net) | server(自建 8006，默认)
MINERU_MODE=server
# 后端地址；留空则按 mode 取默认:
# server -> http://172.19.52.100:8006
# cloud -> https://mineru.net/api/v4
MINERU_BASE_URL=http://172.19.52.100:8006
# 云端密钥 (仅 cloud 模式必填；server 模式留空)
MINERU_API_TOKEN=<YOUR_MINERU_CLOUD_TOKEN>
# 模型版本 / 语言 / 解析参数
MINERU_MODEL_VERSION=vlm
MINERU_LANGUAGE=ch
MINERU_BACKEND=hybrid-engine
MINERU_EFFORT=medium
MINERU_PARSE_METHOD=auto
# 解析产物输出目录
MINERU_OUTPUT_DIR=./data/mineru_mcp_out
# 轮询 / 超时 / 日志
MINERU_POLL_INTERVAL=10
MINERU_TIMEOUT=600
MINERU_LOG_LEVEL=INFO
# SSE / streamable-http 监听
MINERU_SSE_HOST=127.0.0.1
MINERU_SSE_PORT=8765
占位符说明：
<YOUR_MINERU_CLOUD_TOKEN> — 在 mineru.net 控制台获取；仅 cloud 模式需要。
server 模式无需密钥，可直接忽略此项。Python 3.10+，在本 Skill 的 scripts/ 目录建虚拟环境：
# Windows (Git Bash / PowerShell)
python -m venv .venv
.venv/Scripts/activate # PowerShell: .venv\Scripts\Activate.ps1
# Linux / macOS
python3 -m venv .venv && source .venv/bin/activate
安装依赖 (国内可用清华镜像加速)：
pip install mcp requests pydantic
# 镜像加速:
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple mcp requests pydantic
离线自检 (不发网络，验证依赖 / 工具注册 / zip 抽取是否正常)：
python scripts/mineru_mcp_server.py --self-test
# 全部 [ok] 且末尾出现 self-test PASSED 即环境就绪。
下方
PYTHON指 venv 内解释器 (.venv/bin/python或.venv/Scripts/python.exe)；SCRIPT指scripts/mineru_mcp_server.py的绝对路径，请按本机实际替换。
# stdio (默认，供 Claude Code 等本地 MCP 客户端连接)
PYTHON SCRIPT --mode server # 自建 8006，无需密钥
PYTHON SCRIPT --mode cloud --api-token <token> # 线上 mineru.net
# SSE (供远程客户端，默认监听 127.0.0.1:8765)
PYTHON SCRIPT --mode server --transport sse --port 8765
# streamable-http
PYTHON SCRIPT --mode server --transport streamable-http --port 8765
云端密钥也可用环境变量注入，避免命令行裸露 (值见第 4 节)：
# Windows
set MINERU_API_TOKEN=<YOUR_MINERU_CLOUD_TOKEN>
# Linux / macOS
export MINERU_API_TOKEN=<YOUR_MINERU_CLOUD_TOKEN>
编辑 ~/.claude.json 的 mcpServers 字段，按本机绝对路径填入 PYTHON 与 SCRIPT：
"mineru": {
"command": "<venv内python绝对路径>",
"args": ["<本脚本绝对路径>", "--mode", "server"]
}
云端模式把 args 改为：
["<本脚本绝对路径>", "--mode", "cloud", "--api-token", "<YOUR_MINERU_CLOUD_TOKEN>"]
或保留 --mode cloud 再用环境变量 MINERU_API_TOKEN 传 token。
parse_document| 参数 | 默认 | 说明 |
|---|---|---|
file_path |
(必填) | 待解析文件的本地绝对路径 (必须 MCP 服务进程可读) |
filename |
"" |
原始文件名 (扩展名决定解析行为)；留空取 file_path 文件名 |
mode |
"" |
单次覆盖后端 cloud/server；留空走启动配置 |
language |
"" |
OCR/版面语言 ch/en；留空走配置 |
enable_table |
True |
启用表格识别 |
enable_formula |
True |
启用公式识别 |
is_ocr |
False |
强制 OCR (优先数字文本) |
backend |
"" |
服务器模式后端 (默认 hybrid-engine)；仅 server 生效 |
effort |
"" |
服务器模式算力 low/medium/high；仅 server 生效 |
parse_method |
"" |
服务器模式解析方法 auto/ocr/txt；仅 server 生效 |
poll_interval |
0 |
轮询间隔秒 (0=走配置默认 10) |
timeout |
0 |
总超时秒 (0=走配置默认 600) |
返回 JSON：成功含 markdown(超 ~5 万字符截断，全文始终写入 full_markdown_path)、
page_count/char_count/image_count、out_dir、images_dir、content_list_path、result_zip_path；失败含 ok=false 与 error。
注意：
cloud模式必须在启动服务时填写密钥 (--api-token或MINERU_API_TOKEN)，否则返回明确的缺密钥错误。
health_check| 参数 | 默认 | 说明 |
|---|---|---|
mode |
"" |
单次覆盖后端 cloud/server；留空走启动配置 |
返回 JSON：含 mode/base_url/api_token_configured/reachable/http_status 等。
server 模式 GET /tasks；cloud 模式探测鉴权 (需 token，非 401 即通过)。
| 现象 | 处理 |
|---|---|
| cloud 模式返回缺密钥错误 | 填写 MINERU_API_TOKEN (第 4 节)，或改用 --mode server |
| 云端 HTTP 401 | apiToken 无效 / 过期，到 mineru.net 控制台重新获取 |
| server 模式 unreachable | 确认 172.19.52.100:8006 可达；自建地址不同则覆盖 MINERU_BASE_URL |
| 轮询超时 | 调大 MINERU_TIMEOUT (默认 600s) / MINERU_POLL_INTERVAL |
| markdown 被截断 | 正常行为，全文见返回的 full_markdown_path |
| 依赖缺失 | pip install mcp requests pydantic，再跑 --self-test |
