Mineru

What it does

When your agent uses it

• Converting PDF/Word/PPT/Excel/image to Markdown
• Extracting text
• Running OCR on scanned docs
• Batch-parsing a folder in parallel

Example prompts

• “/mineru”

Requirements

• Python 3
• A credential in MINERU_TOKEN

What it can do on your machine

Read from SKILL.md and the folder at commit 02433d8. It shows what the files ask for, not the result of running them.

• Tool permissions

  Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

  From allowed-tools in the SKILL.md frontmatter.

• Runs code

  Ships 1 file in scripts/, which the agent can run.

  Shell commands in SKILL.md call:

  • python3
  • uv
  • pip

  From the folder's file list and the shell code blocks in SKILL.md.

• Network

  Hosts in commands or code, which the agent is likely to contact:

  • mineru.net

  Also links to:

  • peps.python.org
  • docs.astral.sh

  From URLs in SKILL.md, links to its own repository left out.

• Credentials

  Names these keys or tokens, usually read from environment variables:

  • MINERU_TOKEN

  From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Mineru loads about 1.4k tokens when it runs, and up to ~9.5k if it reads all its reference files. Until then it costs about 136 tokens; SKILL.md has 301 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~136

When it runs · the whole SKILL.md, loaded when a task matches

~1.4k

With references · SKILL.md plus every file in references/, read only if the agent opens them

~9.5k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from Nebutra/MinerU-Skill at commit 02433d8, republished under its MIT licence (© Nebutra). 301 words, ~1,394 tokens.

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

metadata.version

3.3.1

metadata.argument-hint

<pdf-file-or-url>

# 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

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

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

python3 scripts/mineru_mcp.py

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

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

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

© Nebutra, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 62 other files (scripts, references, assets) in the repository root of Nebutra/MinerU-Skill.

• SKILL.md
• .claude-plugin/plugin.json
• .github/dependabot.yml
• .github/workflows/ci.yml
• .github/workflows/publish-skill.yml
• .github/workflows/release.yml
• .gitignore
• LICENSE
• README.md
• README_CN.md
• assets/mineru-skill.jpg
• pyproject.toml
• references/api_reference.md
• references/comparison.md
• references/integrations.md
• requirements.txt
• … and 47 more

Open the folder on GitHubat commit 02433d8