mineru

MinerU PDF 解析器

将 PDF、Office（Word/PPT/Excel）和图像文件解析为简洁的 Markdown，支持 LaTeX 公式、表格、图像和 OCR。一个零依赖脚本，两种后端，自动路由。

零配置快速开始（无需令牌，无需安装）

# Parse a local file or URL — the Agent API needs no login
python3 scripts/mineru.py paper.pdf

# Pipe the Markdown straight back to an agent
python3 scripts/mineru.py paper.pdf --stdout

# Machine-readable status for tool pipelines
python3 scripts/mineru.py paper.pdf --json

无需 pip install，无需 API 密钥。免费 Agent API 可处理 ≤ 10 MB / ≤ 20 页的文件。

使用 uv 运行（零安装，由 uv 管理 Python）

scripts/mineru.py 携带 PEP 723 内联元数据，因此 uv 可以直接运行它——无需 venv，无需 pip install，并使用由 uv 管理的解释器：

uv run scripts/mineru.py paper.pdf --stdout       # zero-install run
uv run --no-project --with pytest pytest -q       # dev suite via uv

高级模式（令牌）——大文件、批量处理、额外格式

export MINERU_TOKEN="..."          # https://mineru.net/apiManage/token

# Parallel batch a directory, resume on re-run
python3 scripts/mineru.py ./pdfs/ --output ./out/ --workers 8 --resume

# Export DOCX/HTML/LaTeX alongside Markdown (auto-routes to the Standard API)
python3 scripts/mineru.py report.pdf --format docx --format latex

设置令牌后，工具会自动路由：单个小文件仍使用免费 Agent API；任何大文件（> 10 MB / > 20 页）、批量任务或需要额外导出格式的任务，都会使用 Standard API（≤ 200 MB / ≤ 200 页）。如果 Agent API 遇到大小或页数限制，会自动升级到 Standard API。

支持的模态

模态	扩展名	OCR
PDF	.pdf	--ocr
图像	.png .jpg .jpeg .jp2 .webp .gif .bmp	内置
Word	.doc .docx	—
幻灯片	.ppt .pptx	—
电子表格	.xls .xlsx	—
HTML	.html（Standard API，MinerU-HTML 模型）	—

常用选项

INPUT...          One or more files, a directory, or a URL
--output, -o      Output directory (default: ./output)
--api             auto | agent | standard   (default: auto)
--model           pipeline | vlm | MinerU-HTML  (default: vlm)
--format          docx | html | latex  (repeatable; forces Standard API)
--lang            OCR/document language (default: ch)
--ocr             Enable OCR for scanned documents
--pages           Page range, e.g. "1-10" or "2,4-6"
--workers, -w     Concurrent submit/upload/download slots (default: 8)
--resume          Skip inputs already parsed
--stdout          Print Markdown to stdout
--json            Print machine-readable status to stdout
--to SINK         Deliver into a content tool (repeatable); --list-sinks to enumerate
--obsidian PATH   Shortcut for --to obsidian with this vault
--engine          cloud | local | auto  (local/auto parse born-digital PDFs offline)
--split           Split oversized PDFs past the page caps, parse parts, merge (needs pypdf)
--chunk           Emit heading-aware RAG chunks (.chunks.json + --json)
--doctor          Environment self-check and exit

MCP 服务

通过 MCP 暴露 MinerU（零依赖的 stdio JSON-RPC），使 MCP 宿主可以调用它：

python3 scripts/mineru_mcp.py

工具：mineru_parse、mineru_parse_to（解析并发送到目标端）、mineru_list_sinks。

发送到你的工具（--to）

解析一次，然后通过各内容工具的官方途径发送 Markdown：

python3 scripts/mineru.py paper.pdf --to obsidian --to notion --to feishu

目标：obsidian logseq siyuan notion linear yuque coda slack feishu confluence onenote ticktick dingtalk airtable wecom（均为 零依赖），以及通过可选扩展支持的 roam 和 wps。每个目标都会从环境变量读取配置 （运行 --list-sinks）。各目标的身份验证、保真度和图像说明： references/integrations.md。

输出

output/
└── document-name/
    ├── document-name.md    # clean Markdown
    └── images/             # extracted figures (Standard API)

性能（实测）

通过免费 Agent API 处理官方演示 PDF 的端到端延迟： 冷启动 ≈ 14 s · 热启动 ≈ 13 s（提交 → 轮询 → 下载）。批量处理可通过 --workers 扩展。数据来自 tests/test_live.py 中无模拟的实时基准测试。

测试

python3 -m pytest                      # fast unit suite (offline)
MINERU_LIVE=1 python3 -m pytest -m live -s   # real API + benchmark (no mocks)

API 参考

请参阅 references/api_reference.md。官方文档： https://mineru.net/apiManage/docs · 令牌：https://mineru.net/apiManage/token