Skip to content
Back to search

mineru

SkillWorks with Claude CodeGitHub

"An AI-Native skill for parsing PDF / Office / image files into clean Markdown with MinerU — a fast, zero-config document parser for AI agents. Works with NO token via the lightweight Agent API and auto-upgrades to the Standard API (token) for large files, batches, and DOCX/HTML/LaTeX export. Use when: (1) Converting PDF/Word/PPT/Excel/image to Markdown, (2) Extracting text, tables, formulas, or running OCR on scanned docs, (3) Batch-parsing a folder in parallel, (4) Piping parsed Markdown straight back to an agent or into Obsidian."

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/nebutra--mineru-skill/badge.svg)](/listings/nebutra--mineru-skill)

HTML

<a href="/listings/nebutra--mineru-skill"><img src="/api/listings/nebutra--mineru-skill/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Vercel Skills (recommended)

npx skills add Nebutra/MinerU-Skill

Supported: Claude Code, Antigravity, Codex, Cursor, OpenClaw, Hermes Agent — and 35+ more.

Smithery

npx -y skills add https://smithery.ai/skills/nebutra/mineru-skill

Or open the [listing](https://smithery.ai/skills/nebutra/mineru-skill) and pick your agent (Claude Code, Codex, Cursor, Windsurf & 20+ more).

OpenClaw

git clone https://github.com/Nebutra/MinerU-Skill.git ~/openclaw-skills/mineru/
# No token needed to start. Optional: export MINERU_TOKEN=...  (https://mineru.net/apiManage/token)

ClawHub

clawhub install mineru-skill          # or: openclaw skills install mineru-skill

Claude Code / Cursor / Windsurf

git clone https://github.com/Nebutra/MinerU-Skill.git ~/.claude/skills/mineru/

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 147 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: mineru
  3. description: "An AI-Native skill for parsing PDF / Office / image files into clean Markdown with MinerU — a fast, zero-config document parser for AI agents. Works with NO token via the lightweight Agent API and auto-upgrades to the Standard API (token) for large files, batches, and DOCX/HTML/LaTeX export. Use when: (1) Converting PDF/Word/PPT/Excel/image to Markdown, (2) Extracting text, tables, formulas, or running OCR on scanned docs, (3) Batch-parsing a folder in parallel, (4) Piping parsed Markdown straight back to an agent or into Obsidian."
  4. homepage: https://mineru.net
  5. metadata:
  6. author: Nebutra
  7. version: "3.3.1"
  8. argument-hint: <pdf-file-or-url>
  9. openclaw:
  10. emoji: "📄"
  11. requires:
  12. bins: ["python3"]
  13. ---
  14. # MinerU PDF Parser
  15. Parse PDF, Office (Word/PPT/Excel), and image files into clean Markdown — with
  16. LaTeX formulas, tables, images, and OCR. One zero-dependency script, two backends,
  17. automatic routing.
  18. ## Zero-config quick start (no token, no install)
  19. ```bash
  20. # Parse a local file or URL — the Agent API needs no login
  21. python3 scripts/mineru.py paper.pdf
  22. # Pipe the Markdown straight back to an agent
  23. python3 scripts/mineru.py paper.pdf --stdout
  24. # Machine-readable status for tool pipelines
  25. python3 scripts/mineru.py paper.pdf --json
  26. ```
  27. No `pip install`, no API key. The free **Agent API** handles files ≤ 10 MB / ≤ 20 pages.
  28. ### Run with uv (zero-install, managed Python)
  29. `scripts/mineru.py` carries [PEP 723](https://peps.python.org/pep-0723/) inline
  30. metadata, so [uv](https://docs.astral.sh/uv/) runs it directly — no venv, no
  31. `pip install`, with a uv-managed interpreter:
  32. ```bash
  33. uv run scripts/mineru.py paper.pdf --stdout # zero-install run
  34. uv run --no-project --with pytest pytest -q # dev suite via uv
  35. ```
  36. ## Power mode (token) — large files, batches, extra formats
  37. ```bash
  38. export MINERU_TOKEN="..." # https://mineru.net/apiManage/token
  39. # Parallel batch a directory, resume on re-run
  40. python3 scripts/mineru.py ./pdfs/ --output ./out/ --workers 8 --resume
  41. # Export DOCX/HTML/LaTeX alongside Markdown (auto-routes to the Standard API)
  42. python3 scripts/mineru.py report.pdf --format docx --format latex
  43. ```
  44. When a token is set, the tool **auto-routes**: small single files still use the
  45. free Agent API; anything large (> 10 MB / > 20 pages), batched, or needing extra
  46. export formats uses the **Standard API** (≤ 200 MB / ≤ 200 pages). If the Agent
  47. API hits a size/page limit, it auto-escalates to the Standard API.
  48. ## Supported modalities
  49. | Modality | Extensions | OCR |
  50. |----------|-----------|-----|
  51. | PDF | `.pdf` | `--ocr` |
  52. | Image | `.png .jpg .jpeg .jp2 .webp .gif .bmp` | built-in |
  53. | Word | `.doc .docx` | — |
  54. | Slides | `.ppt .pptx` | — |
  55. | Sheet | `.xls .xlsx` | — |
  56. | HTML | `.html` (Standard API, `MinerU-HTML` model) | — |
  57. ## Common options
  58. ```
  59. INPUT... One or more files, a directory, or a URL
  60. --output, -o Output directory (default: ./output)
  61. --api auto | agent | standard (default: auto)
  62. --model pipeline | vlm | MinerU-HTML (default: vlm)
  63. --format docx | html | latex (repeatable; forces Standard API)
  64. --lang OCR/document language (default: ch)
  65. --ocr Enable OCR for scanned documents
  66. --pages Page range, e.g. "1-10" or "2,4-6"
  67. --workers, -w Concurrent submit/upload/download slots (default: 8)
  68. --resume Skip inputs already parsed
  69. --stdout Print Markdown to stdout
  70. --json Print machine-readable status to stdout
  71. --to SINK Deliver into a content tool (repeatable); --list-sinks to enumerate
  72. --obsidian PATH Shortcut for --to obsidian with this vault
  73. --engine cloud | local | auto (local/auto parse born-digital PDFs offline)
  74. --split Split oversized PDFs past the page caps, parse parts, merge (needs pypdf)
  75. --chunk Emit heading-aware RAG chunks (.chunks.json + --json)
  76. --doctor Environment self-check and exit
  77. ```
  78. ## MCP server
  79. Expose MinerU over MCP (zero-dependency stdio JSON-RPC) so an MCP host can call it:
  80. ```bash
  81. python3 scripts/mineru_mcp.py
  82. ```
  83. Tools: `mineru_parse`, `mineru_parse_to` (parse + deliver to sinks), `mineru_list_sinks`.
  84. ## Deliver into your tools (`--to`)
  85. Parse once and push the Markdown into content tools via each one's official path:
  86. ```bash
  87. python3 scripts/mineru.py paper.pdf --to obsidian --to notion --to feishu
  88. ```
  89. Targets: `obsidian` `logseq` `siyuan` `notion` `linear` `yuque` `coda` `slack`
  90. `feishu` `confluence` `onenote` `ticktick` `dingtalk` `airtable` `wecom` (all
  91. zero-dependency), plus `roam` and `wps` via optional extras. Each reads its config
  92. from env vars (run `--list-sinks`). Per-target auth, fidelity, and image notes:
  93. [references/integrations.md](references/integrations.md).
  94. ## Output
  95. ```
  96. output/
  97. └── document-name/
  98. ├── document-name.md # clean Markdown
  99. └── images/ # extracted figures (Standard API)
  100. ```
  101. ## Performance (real, measured)
  102. End-to-end latency for the official demo PDF via the free Agent API:
  103. **cold ≈ 14 s · warm ≈ 13 s** (submit → poll → download). Batches scale with
  104. `--workers`. Numbers come from the no-mock live benchmark in `tests/test_live.py`.
  105. ## Testing
  106. ```bash
  107. python3 -m pytest # fast unit suite (offline)
  108. MINERU_LIVE=1 python3 -m pytest -m live -s # real API + benchmark (no mocks)
  109. ```
  110. ## API Reference
  111. See [references/api_reference.md](references/api_reference.md). Official docs:
  112. https://mineru.net/apiManage/docs · Token: https://mineru.net/apiManage/token
README.md · README · 369 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <img src="assets/mineru-skill.jpg" alt="MinerU Skill — AI-Native document parsing for the AI-agent era: PDF, Office, images, formulas & tables in; clean Markdown out to your agents, terminal, and the knowledge & content tools you already use" width="100%">
  3. </p>
  4. # MinerU Skill
  5. [![GitHub Release](https://img.shields.io/github/v/release/Nebutra/MinerU-Skill?include_prereleases)](https://github.com/Nebutra/MinerU-Skill/releases) [![Python](https://img.shields.io/badge/Python-3.8+-3776AB.svg?logo=python&logoColor=white)](https://www.python.org/) [![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen.svg)](requirements.txt) [![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE) [![Smithery](https://img.shields.io/badge/Smithery-Available-blue.svg)](https://smithery.ai/skills/nebutra/mineru-skill) [![ClawHub](https://img.shields.io/badge/ClawHub-Available-purple.svg)](https://clawhub.com)
  6. [![GitHub Stars](https://img.shields.io/github/stars/Nebutra/MinerU-Skill?style=social)](https://github.com/Nebutra/MinerU-Skill/stargazers) [![GitHub Forks](https://img.shields.io/github/forks/Nebutra/MinerU-Skill?style=social)](https://github.com/Nebutra/MinerU-Skill/network/members)
  7. **An AI-Native document parser built for AI agents** — turn PDF, Office & image files into clean Markdown with _zero_ API key, _zero_ install, and fast parallel batches.
  8. **[中文文档](README_CN.md)** | **English**
  9. ---
  10. ## ⚡ Try it in 5 seconds (no signup, no token, no pip install)
  11. ```bash
  12. python3 scripts/mineru.py https://cdn-mineru.openxlab.org.cn/demo/example.pdf --stdout
  13. ```
  14. Prefer [uv](https://docs.astral.sh/uv/)? The script ships [PEP 723](https://peps.python.org/pep-0723/)
  15. inline metadata, so uv runs it with a managed Python and zero install:
  16. ```bash
  17. uv run scripts/mineru.py https://cdn-mineru.openxlab.org.cn/demo/example.pdf --stdout
  18. ```
  19. That's it. No account. No API key. No dependencies. The free **Agent API** parses
  20. the PDF and streams clean Markdown straight to your terminal — or to your AI agent.
  21. > Need more power? `export MINERU_TOKEN=...` and the same command auto-upgrades to
  22. > the **Standard API** for 200 MB / 200-page files, parallel batches, and DOCX/HTML/LaTeX export.
  23. ---
  24. ## 🤔 Why not just call MinerU directly?
  25. | | Raw MinerU API / scripts | **MinerU Skill** |
  26. |---|---|---|
  27. | **Start with no token** | ❌ token required | ✅ free Agent API, zero-config |
  28. | **Backend selection** | 🤷 you pick & wire it | ✅ **auto-routes** Agent ⇄ Standard |
  29. | **Install footprint** | `requests` + `aiohttp` | ✅ **zero deps** (stdlib only) |
  30. | **Agent-friendly output** | files only | ✅ `--stdout` Markdown · `--json` status |
  31. | **Modalities** | DIY per format | ✅ PDF · image · Word · PPT · Excel · HTML |
  32. | **Batch + resume** | hand-rolled | ✅ `--workers` + `--resume` built in |
  33. | **Bad-token errors** | cryptic `code None` | ✅ clear "token expired → refresh here" |
  34. | **Obsidian export** | — | ✅ `--obsidian /path/to/vault` |
  35. Built for the **AI-Agent era**: an agent can run it instantly, get Markdown on stdout,
  36. and never touch a config file.
  37. ---
  38. ## How MinerU Skill compares
  39. MinerU Skill is **not a new parsing engine** — it is a zero-config, zero-dependency, agent-native **convenience layer** over [MinerU](https://github.com/opendatalab/MinerU)'s cloud API, with 17 turnkey delivery integrations. Its accuracy is whatever MinerU's cloud serves (solid: MinerU2.5 scores **90.67** on OmniDocBench v1.5, MinerU2.5-Pro **95.69** on v1.6). Our edge is **DX, AI-nativeness, free token-free start, and delivery breadth** — *not* being the most accurate parser, and *not* an offline option. If you need offline/air-gapped parsing, top formula or table fidelity, or RAG-native chunking, a competitor below is the better tool.
  40. ### Comparison matrix
  41. Legend: ✅ yes · ⚠️ partial/qualified · ❌ no. "Same backend" = calls the **same MinerU cloud API** we do, so OCR/table/formula output is **identical to ours** (no quality difference between us and those tools).
  42. | Tool | Type | Offline / self-host | Token-free start | Zero-install (no models) | Accuracy (best public benchmark) | Formula→LaTeX | Tables | Delivery to note/PKM tools | Native MCP |
  43. |---|---|---|---|---|---|---|---|---|---|
  44. | **MinerU Skill** (this) | Cloud wrapper (CLI/skill/MCP) | ⚠️ local for born-digital (`--engine local`) | ✅ free Agent API | ✅ stdlib core | = MinerU cloud (90.67 OmniDocBench v1.5) | Good (MinerU) | Good (MinerU) | ✅ **17 sinks** | ✅ zero-dep MCP |
  45. | MinerU engine (self-hosted) | Self-hosted engine | ✅ fully offline | ✅ (own HW) | ❌ multi-GB torch/VLM + weights | **90.67 / 95.69-Pro** OmniDocBench | Best (owns the model) | SOTA | ❌ | ✅ official MCP |
  46. | Official MinerU MCP | Cloud MCP (same backend) | ❌ cloud | ✅ free Flash tier | ⚠️ pip/uvx, no weights | = ours (same backend) | = ours | = ours | ❌ | ✅ first-party |
  47. | MinerU-Document-Explorer | Local knowledge engine + MCP | ✅ local core | ✅ (cloud parse optional) | ❌ Node + local models | retrieval-grade | n/a (reader) | n/a | ❌ (own index/wiki) | ✅ 15 tools |
  48. | Marker | Self-hosted engine | ✅ offline | ✅ (LLM opt-in) | ❌ PyTorch+Surya, ~3.5–5GB VRAM | 76.1 olmOCR-Bench | Good | Good (0.91 w/LLM) | ❌ | ❌ |
  49. | Docling (IBM) | Self-hosted engine | ✅ offline/air-gap | ✅ | ⚠️ pip + small 258M VLM | strong-for-size; lags MinerU absolute | Good | Good (~0.96 TEDS) | ❌ (RAG framework ingest) | ✅ official MCP |
  50. | olmOCR (Ai2) | Self-hosted VLM | ✅ offline | ✅ (own GPU) | ❌ 12GB+ NVIDIA, no CPU | **82.4 olmOCR-Bench (leads)** | Good | Good | ❌ | ❌ |
  51. | PyMuPDF4LLM | Library (geometric) | ✅ offline | ✅ | ✅ light pip, no GPU | n/a (not ML; fastest on clean PDFs) | None/basic | Basic | ❌ | ❌ |
  52. | Mathpix | Cloud API | ❌ cloud | ❌ $19.99 setup, no free API tier | ✅ thin client | **best math/formula OCR** | **Best (incl. handwriting)** | Good | ❌ | ❌ |
  53. | LlamaParse | Cloud API | ❌ cloud | ❌ key required | ⚠️ pip llama-parse | top GenAI-native (no OmniDocBench #) | Basic-good | Good-excellent | ❌ (RAG indexes) | ✅ hosted MCP |
  54. | Unstructured | Cloud API + OSS lib | ⚠️ OSS self-host (Apache-2.0) | ⚠️ key for hosted | ⚠️ pip + per-format extras | ETL-focused, not a bench leader | Basic | Moderate-good | ❌ (vector DBs) | ✅ official MCP |
  55. | Reducto | Cloud API | ⚠️ VPC/on-prem (enterprise) | ❌ key required | ✅ thin client | **best complex tables (90.2% RD-TableBench, vendor-authored)** | Good | **Best (complex/financial)** | ❌ | ❌ |
  56. | Zerox | Library (cloud-VLM) | ❌ needs cloud LLM | ❌ paid LLM key | ⚠️ needs graphicsmagick+ghostscript | no published benchmarks | Basic (depends on VLM) | Basic-good | ❌ | ❌ |
  57. > Other same-backend MinerU wrappers (linxule/mineru-mcp, mineru-converter-mcp-server, grimoire-skill, nilecui, kesslerio) produce **identical** OCR/table/formula output to us because they hit the same engine. We differ from them only on DX (free token-free default, 17 sinks, --resume/parallel batch, stdlib-only core), **not** quality. mineru-converter even auto-splits >200MB / segments >600-page docs — exceeding the cloud caps we are bound by.
  58. ### Where MinerU Skill genuinely wins
  59. - **Token-free, zero-install start** — the free Agent API needs no key, account, or `pip install` (the script's core is pure Python stdlib). Most cloud APIs (LlamaParse, Mathpix, Reducto, hosted Unstructured) require a key from page one.
  60. - **17 one-shot delivery sinks** (Obsidian, Logseq, SiYuan, Notion, Confluence, OneNote, Coda, Yuque, Lark, Slack, DingTalk, WeCom, TickTick, Linear, Airtable, + Roam/WPS via optional extras) — *no* parsing engine or enterprise/RAG API here ships note/PKM delivery. (15 sinks are zero-dependency; Roam/WPS lazy-load one library.)
  61. - **Agent-native ergonomics**: `--stdout` Markdown + `--json` status, auto-routing Agent⇄Standard with size/page auto-escalation, `--resume` dedup, and parallel `--workers` batch, all in one ~54KB script.
  62. ### When to use something else (honest take)
  63. - **Confidential / regulated / air-gapped documents** → we **cannot help**: we upload every file to MinerU's cloud. Use self-hosted **MinerU engine**, **Marker**, **Docling**, **olmOCR**, **PyMuPDF4LLM**, or self-hostable **Unstructured** — all run 100% offline with no cloud dependency and no upload-size caps.
  64. - **Maximum accuracy / version control** → self-host **MinerU2.5-Pro** for the same-or-better results (95.69 OmniDocBench v1.6) with no 10MB/20-page or 200MB/200-page caps. Note benchmarks disagree: **olmOCR leads olmOCR-Bench (82.4 vs MinerU 75.8)** while MinerU leads OmniDocBench — pick by your doc type.
  65. - **Math / formula OCR (incl. handwriting)** → **Mathpix** is the de-facto standard and clearly beats MinerU on pure formula fidelity.
  66. - **Complex / financial tables, SLAs, SOC2/HIPAA, on-prem** → **Reducto** (90.2% RD-TableBench).
  67. - **RAG pipelines** (chunking, structured JSON-Schema extraction, official MCP, framework ingestion) → **LlamaParse**, **Unstructured**, **Docling**, or **Reducto**.
  68. - **Huge born-digital PDF corpora where speed > fidelity** → **PyMuPDF4LLM** (hundreds of pages/sec on plain CPU, no GPU, no cloud).
  69. - **First-party reliability / native MCP in Claude/Cursor/Windsurf** → the **official MinerU MCP server** tracks API and format changes day-one and matches our free token-free tier; we are a third-party wrapper that can lag and ship no MCP server.
  70. > On speed: our ~13–14s figure is one small demo PDF round-tripped through the cloud — *not* a like-for-like win over self-hosted GPU engines (Marker ~0.18s/page, MinerU ~2.12 pages/sec on an A100), which are far faster at real scale. We only beat slow Apple-Silicon-CPU local runs of small docs, and our latency benchmark measures **latency, not accuracy**.
  71. > Full per-tool breakdown with source links: **[references/comparison.md](references/comparison.md)**.
  72. ---
  73. ## 🚀 Install as a Skill (Claude Code, Codex, Cursor & 35+ agents)
  74. ### Vercel Skills (recommended)
  75. ```bash
  76. npx skills add Nebutra/MinerU-Skill
  77. ```
  78. Supported: Claude Code, Antigravity, Codex, Cursor, OpenClaw, Hermes Agent — and 35+ more.
  79. ### Smithery
  80. [![Install in Smithery](https://img.shields.io/badge/Install%20in-Smithery-blue)](https://smithery.ai/skills/nebutra/mineru-skill)
  81. ```bash
  82. npx -y skills add https://smithery.ai/skills/nebutra/mineru-skill
  83. ```
  84. Or open the [listing](https://smithery.ai/skills/nebutra/mineru-skill) and pick your agent (Claude Code, Codex, Cursor, Windsurf & 20+ more).
  85. ### OpenClaw
  86. ```bash
  87. git clone https://github.com/Nebutra/MinerU-Skill.git ~/openclaw-skills/mineru/
  88. # No token needed to start. Optional: export MINERU_TOKEN=... (https://mineru.net/apiManage/token)
  89. ```
  90. ### ClawHub
  91. ```bash
  92. clawhub install mineru-skill # or: openclaw skills install mineru-skill
  93. ```
  94. ### Claude Code / Cursor / Windsurf
  95. ```bash
  96. git clone https://github.com/Nebutra/MinerU-Skill.git ~/.claude/skills/mineru/
  97. ```
  98. ---
  99. ## 💬 Talk to your AI
  100. ```
  101. You: 解析这些考研数学真题 PDF 到我的 Obsidian
  102. AI: 📚 1 input(s) · workers=8 · token set
  103. ✅ [agent/pdf] 1993年考研数学(一)真题 (13.9s)
  104. ✅ [standard/pdf] 2024年考研数学(一)真题 (28.4s) ← auto-upgraded (large file)
  105. ...
  106. 📁 saved to Obsidian/考研/数学一/
  107. ```
  108. ```
  109. 把 ./papers/ 目录下所有 PDF 并行解析,跳过已处理的,直接存到 Obsidian
  110. ```
  111. ---
  112. ## 🧩 Supported formats — PDF, Word, PPT, Excel, image & HTML
  113. | Modality | Extensions | OCR |
  114. |----------|-----------|-----|
  115. | 📄 PDF | `.pdf` | `--ocr` |
  116. | 🖼️ Image | `.png .jpg .jpeg .jp2 .webp .gif .bmp` | built-in |
  117. | 📝 Word | `.doc .docx` | — |
  118. | 📊 Slides | `.ppt .pptx` | — |
  119. | 📈 Sheet | `.xls .xlsx` | — |
  120. | 🌐 HTML | `.html` (Standard, `MinerU-HTML`) | — |
  121. LaTeX formulas, structured tables, and extracted images are preserved.
  122. ---
  123. ## 🛠️ CLI reference
  124. ```bash
  125. # Zero-config single file or URL
  126. python3 scripts/mineru.py paper.pdf
  127. # Pipe Markdown back to an agent / capture machine status
  128. python3 scripts/mineru.py paper.pdf --stdout
  129. python3 scripts/mineru.py paper.pdf --json
  130. # Parallel batch a directory, resume on re-run, copy into Obsidian
  131. export MINERU_TOKEN=...
  132. python3 scripts/mineru.py ./pdfs/ --output ./out/ --workers 8 --resume \
  133. --obsidian "~/Obsidian/MyVault/"
  134. # Scanned docs with OCR; export extra formats (auto-routes to Standard API)
  135. python3 scripts/mineru.py scan.pdf --ocr --lang en --format docx --format latex
  136. ```
  137. | Option | Description |
  138. |--------|-------------|
  139. | `INPUT...` | File(s), a directory, or a URL |
  140. | `--output, -o` | Output directory (default `./output`) |
  141. | `--api` | `auto` · `agent` · `standard` (default `auto`) |
  142. | `--model` | `pipeline` · `vlm` · `MinerU-HTML` (default `vlm`) |
  143. | `--format` | `docx` · `html` · `latex` (repeatable; forces Standard API) |
  144. | `--ocr` / `--lang` | Enable OCR / set language (default `ch`) |
  145. | `--pages` | Page range, e.g. `1-10` or `2,4-6` |
  146. | `--workers, -w` | Concurrent submit/upload/download slots (default 8) |
  147. | `--resume` | Skip inputs already parsed |
  148. | `--stdout` / `--json` | Markdown to stdout / machine status to stdout |
  149. | `--to SINK` | Deliver into a content tool (repeatable) — see below |
  150. | `--obsidian PATH` | Shortcut for `--to obsidian` with this vault |
  151. | `--engine` | `cloud` · `local` · `auto` — `local`/`auto` parse born-digital PDFs **offline** via `pymupdf4llm` |
  152. | `--split` | Slice oversized PDFs past the page caps, parse parts, merge (needs `pypdf`) |
  153. | `--chunk` / `--chunk-size` | Emit heading-aware RAG chunks (`.chunks.json` + `--json`) |
  154. | `--list-sinks` | List delivery targets and their required env vars |
  155. | `--doctor` | Environment self-check (Python, API, token, extras, sinks) |
  156. > **MCP server:** run `python3 scripts/mineru_mcp.py` to expose MinerU over MCP
  157. > (zero-dep stdio JSON-RPC) — tools `mineru_parse`, `mineru_parse_to`, `mineru_list_sinks`.
  158. > Optional extras: `pip install "mineru-skill[split]" "mineru-skill[local]"`.
  159. ---
  160. ## 🔌 Deliver anywhere (`--to`)
  161. Parse once, push straight into your tools using each one's **official** ingestion
  162. path (no hacky converters). Fan out to several at once:
  163. ```bash
  164. python3 scripts/mineru.py paper.pdf --to obsidian --to notion --to slack
  165. ```
  166. | | Tools | `--to` |
  167. |---|---|---|
  168. | 📓 Notes (local) | Obsidian · Logseq · SiYuan | `obsidian` `logseq` `siyuan` |
  169. | 🌐 Docs / Wiki | Notion · Confluence · OneNote · Coda · Yuque 语雀 · Lark 飞书 | `notion` `confluence` `onenote` `coda` `yuque` `feishu` |
  170. | 💬 Chat / Tasks | Slack · DingTalk 钉钉 · WeCom 企业微信 · TickTick 滴答 · Linear · Airtable | `slack` `dingtalk` `wecom` `ticktick` `linear` `airtable` |
  171. | 🧩 Optional (extras) | Roam · WPS 金山文档 | `roam` `wps` |
  172. Each target uses its native Markdown path where one exists (Obsidian, Logseq,
  173. SiYuan, Linear, Yuque, Coda, Lark, TickTick) or a faithful conversion where the
  174. tool requires it (Notion blocks; Confluence/OneNote HTML; Roam outline; WPS DOCX).
  175. **15 targets are zero-dependency**; Roam & WPS lazy-load a library only when used
  176. (`pip install "mineru-skill[roam]" "mineru-skill[wps]"`). Full per-target auth,
  177. fidelity, and image notes are in
  178. **[references/integrations.md](references/integrations.md)**. Run
  179. `python3 scripts/mineru.py --list-sinks` to see the required env vars.
  180. ---
  181. ## 📁 Output structure
  182. ```
  183. output/
  184. └── document-name/
  185. ├── document-name.md # clean Markdown
  186. └── images/ # extracted figures (Standard API)
  187. ```
  188. ---
  189. ## 📊 Performance (real, no-mock benchmark)
  190. End-to-end latency for the official demo PDF via the **free Agent API**
  191. (submit → poll → download), measured by `tests/test_live.py`:
  192. | Run | Latency |
  193. |-----|---------|
  194. | Cold | ~14 s |
  195. | Warm | ~13 s |
  196. | p50 | ~14 s |
  197. Batches scale with `--workers`. Reproduce it yourself:
  198. ```bash
  199. MINERU_LIVE=1 python3 -m pytest -m live -s
  200. ```
  201. > **Honest caveat:** this measures **latency** (one small demo PDF round-tripped
  202. > through the cloud), **not accuracy**, and it is **not** a speed win over
  203. > self-hosted GPU engines (Marker ~0.18 s/page, MinerU ~2.12 pages/s on an A100),
  204. > which are far faster at scale. See [how we compare](#how-mineru-skill-compares).
  205. ---
  206. ## 🔑 API token (optional)
  207. The Agent API needs **no token**. Set one to unlock the Standard API (large files,
  208. batch, DOCX/HTML/LaTeX):
  209. 1. Visit **[MinerU Token Management](https://mineru.net/apiManage/token)**
  210. 2. Create a free token
  211. 3. `export MINERU_TOKEN="your-token-here"`
  212. **Free Standard quota:** 1000 pages/day at highest priority · 200 MB / 200 pages max.
  213. > 📖 Official API docs: https://mineru.net/apiManage/docs
  214. ---
  215. ## 🧪 Develop & test
  216. ```bash
  217. python3 -m pytest # fast unit suite (offline, no network)
  218. MINERU_LIVE=1 python3 -m pytest -m live -s # real API + benchmark (no mocks)
  219. uv run --no-project --with pytest pytest -q # same suite via uv (managed Python)
  220. ```
  221. Zero runtime dependencies — `scripts/mineru.py` is pure standard library, and runs
  222. under either `python3` or `uv run` (PEP 723 inline metadata).
  223. ---
  224. ## ⭐ Star History
  225. <a href="https://www.star-history.com/#Nebutra/MinerU-Skill&type=timeline&legend=bottom-right">
  226. <picture>
  227. <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=Nebutra/MinerU-Skill&type=timeline&theme=dark&legend=bottom-right" />
  228. <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=Nebutra/MinerU-Skill&type=timeline&legend=bottom-right" />
  229. <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=Nebutra/MinerU-Skill&type=timeline&legend=bottom-right" />
  230. </picture>
  231. </a>
  232. ---
  233. ## 🏗️ How it works
  234. ```
  235. your file / URL
  236. │
  237. ▼
  238. ┌──────────────────────────────────────────────┐
  239. │ mineru.py (zero-dep, AI-Native) │
  240. │ detect modality → choose API (auto) │
  241. │ • no token / small → Agent API │
  242. │ • token + big/batch → Standard API │
  243. │ • Agent size/page limit → auto-escalate │
  244. │ submit → poll → download → write Markdown │
  245. └──────────────────────────────────────────────┘
  246. │
  247. ▼
  248. Markdown (+ images) → stdout · files · Obsidian · JSON status
  249. ```
  250. ---
  251. ## 🤝 Contributing
  252. Fork → Branch → Commit → Push → PR. Issues and ideas welcome — we actively maintain
  253. this skill and ship around the MinerU ecosystem for AI agents.
  254. ## 📝 License
  255. MIT — see [LICENSE](LICENSE).
  256. ## 🙏 Acknowledgments
  257. - [MinerU](https://mineru.net/) — PDF parsing engine ([token](https://mineru.net/apiManage/token) · [docs](https://mineru.net/apiManage/docs))
  258. - [OpenClaw](https://openclaw.ai/) — AI skill framework
  259. - [ClawHub](https://clawhub.com) — skill marketplace
  260. ---
  261. <div align="center">
  262. **If this skill saves you time, give it a ⭐ — it helps other agents find it.**
  263. Made with ❤️ by [Nebutra](https://github.com/Nebutra)
  264. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.