mineru · nebutra — Claude Code skill: what it does, how to install
mineru converts PDF, Office files, and images into clean Markdown with LaTeX math, tables, and OCR without requiring an API key up front.
MIT 19 installs ★ 138 updated 2026-09-24
npx skills add Nebutra/MinerU-Skill --skill mineru -a claude-codeWhat mineru does
This skill runs scripts/mineru.py using Python 3 or uv. For single files up to 10 MB and 20 pages, it connects to the free Agent API without authentication. When handling larger inputs or directory batches, it switches to the Standard API once MINERU_TOKEN is configured.
The parser extracts text, processes scanned files with --ocr, and extracts figures alongside tables. Output can be piped straight to terminal stdout, exported to DOCX or LaTeX, or synced into external destinations using --to for platforms like Obsidian and Notion. An included stdio server in scripts/mineru_mcp.py also exposes the tool over MCP.
Without an API token, any document exceeding 20 pages fails to process.
What it helps with
- convert complex PDF papers into clean Markdown with LaTeX formulas
- run OCR on scanned documents and image files
- batch-process a directory of Office files with multiple parallel workers
- export parsed document text directly into an Obsidian vault or Notion
Example prompts for the agent
- Parse paper.pdf with mineru and print the Markdown to stdout
- Run OCR on scan.png and export the result to docx
- Batch parse all files in ./reports/ using mineru with 8 workers
How to install mineru
1Skills CLI (Vercel)
npx skills add Nebutra/MinerU-Skill --skill mineru -a claude-code2Manually: put the files in place
~/.claude/skills/nebutra-mineru/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/nebutra-mineru/
1Skills CLI (Vercel)
npx skills add Nebutra/MinerU-Skill --skill mineru -a codex2Manually: put the files in place
.agents/skills/nebutra-mineru/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add Nebutra/MinerU-Skill --skill mineru -a cursor2Manually: put the files in place
.cursor/skills/nebutra-mineru/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install Nebutra/MinerU-Skill nebutra-mineru2Manually: put the files in place
.github/skills/nebutra-mineru/SKILL.md1Skills CLI (Vercel)
npx skills add Nebutra/MinerU-Skill --skill mineru -a gemini-cli2Platform CLI
gemini skills install https://github.com/Nebutra/MinerU-SkillManually: put the files in place
.devin/skills/nebutra-mineru/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add Nebutra/MinerU-Skill --skill mineru -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about mineru
How to install mineru in Claude Code?
Run npx skills add Nebutra/MinerU-Skill --skill nebutra-mineru -a claude-code in your terminal.
What does mineru do?
It converts PDF, Word, Excel, PPT, and image files into Markdown, preserving LaTeX formulas, tables, and embedded images.
Is an API key required to run mineru?
No token is needed for files under 10 MB and 20 pages via Agent API. Larger files or batch runs require setting MINERU_TOKEN.
Source text
SKILL.md · MIT
---
name: mineru
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."
homepage: https://mineru.net
metadata:
author: Nebutra
version: "3.3.1"
argument-hint: <pdf-file-or-url>
openclaw:
emoji: "📄"
requires:
bins: ["python3"]
---
# MinerU PDF Parser
Parse PDF, Office (Word/PPT/Excel), and image files into clean Markdown — with
LaTeX formulas, tables, images, and OCR. One zero-dependency script, two backends,
automatic routing.
## Zero-config quick start (no token, no install)
```bash
# 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
```
No `pip install`, no API key. The free **Agent API** handles files ≤ 10 MB / ≤ 20 pages.
### Run with uv (zero-install, managed Python)
`scripts/mineru.py` carries [PEP 723](https://peps.python.org/pep-0723/) inline
metadata, so [uv](https://docs.astral.sh/uv/) runs it directly — no venv, no
`pip install`, with a uv-managed interpreter:
```bash
uv run scripts/mineru.py paper.pdf --stdout # zero-install run
uv run --no-project --with pytest pytest -q # dev suite via uv
```
## Power mode (token) — large files, batches, extra formats
```bash
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
```
When a token is set, the tool **auto-routes**: small single files still use the
free Agent API; anything large (> 10 MB / > 20 pages), batched, or needing extra
export formats uses the **Standard API** (≤ 200 MB / ≤ 200 pages). If the Agent
API hits a size/page limit, it auto-escalates to the Standard API.
## Supported modalities
| Modality | Extensions | OCR |
|----------|-----------|-----|
| PDF | `.pdf` | `--ocr` |
| Image | `.png .jpg .jpeg .jp2 .webp .gif .bmp` | built-in |
| Word | `.doc .docx` | — |
| Slides | `.ppt .pptx` | — |
| Sheet | `.xls .xlsx` | — |
| HTML | `.html` (Standard API, `MinerU-HTML` model) | — |
## Common options
```
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 server
Expose MinerU over MCP (zero-dependency stdio JSON-RPC) so an MCP host can call it:
```bash
python3 scripts/mineru_mcp.py
```
Tools: `mineru_parse`, `mineru_parse_to` (parse + deliver to sinks), `mineru_list_sinks`.
## Deliver into your tools (`--to`)
Parse once and push the Markdown into content tools via each one's official path:
```bash
python3 scripts/mineru.py paper.pdf --to obsidian --to notion --to feishu
```
Targets: `obsidian` `logseq` `siyuan` `notion` `linear` `yuque` `coda` `slack`
`feishu` `confluence` `onenote` `ticktick` `dingtalk` `airtable` `wecom` (all
zero-dependency), plus `roam` and `wps` via optional extras. Each reads its config
from env vars (run `--list-sinks`). Per-target auth, fidelity, and image notes:
[references/integrations.md](references/integrations.md).
## Output
```
output/
└── document-name/
├── document-name.md # clean Markdown
└── images/ # extracted figures (Standard API)
```
## Performance (real, measured)
End-to-end latency for the official demo PDF via the free Agent API:
**cold ≈ 14 s · warm ≈ 13 s** (submit → poll → download). Batches scale with
`--workers`. Numbers come from the no-mock live benchmark in `tests/test_live.py`.
## Testing
```bash
python3 -m pytest # fast unit suite (offline)
MINERU_LIVE=1 python3 -m pytest -m live -s # real API + benchmark (no mocks)
```
## API Reference
See [references/api_reference.md](references/api_reference.md). Official docs:
https://mineru.net/apiManage/docs · Token: https://mineru.net/apiManage/token
© Nebutra · MIT · Nebutra/MinerU-Skill
Similar skills
All skills for Office documents →mineru by other authors comes first.