Mineru

MCP设计创作

提供方 linxule · 包名 mineru-mcp

设计创作 stdio · 本地进程 API Key 社区 / 第三方 Claude DesktopClaudeCursorVS Code
查看接入方式

mineru-mcp MCP server for [MinerU](https://mineru.net) document parsing API — extract text, tables, and formulas from PDFs, DOCs, and images. Features - VLM model — 90%+ accuracy for complex documents - Pipeline model — Fast processing for simple documents - Local file upload — Upload files from disk for batch parsing - Batch processing — Parse up to 200 documents at once -

一句话选型结论

按资料字段整理

Mineru 属于设计创作类 MCP 服务器,stdio · 本地进程,API Key,可直接接入 Claude Desktop、Claude、Cursor 等,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类设计创作 传输方式stdio · 本地进程 鉴权API Key 部署方式本地部署
GitHub 星标 未标注 仓库热度,无公开仓库时显示未标注
工具数 未标注 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

设计创作
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量未标注暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

pdf ocr document parsing data extraction batch processing

支持客户端

适用场景

pdfocrdocument parsing

安装与配置

stdio · 本地进程 API Key
客户端在本机拉起子进程,数据不出本机
npx -y mineru-mcp

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 node,再按安装命令拉取依赖。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后随便调一个只读工具,确认能返回结果,再接入正式流程。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
出图与素材

生成配图、图标与素材。

设计稿处理

读取设计稿、批量改尺寸或导出。

内容生成

按主题生成文案与视觉草稿。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。
  • 已适配 Claude Desktop、Claude、Cursor,换客户端不用重新研究配置。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 使用前要准备好API Key对应的凭据,并按最小权限配置。
  • 资料没标注工具数量,实际能力要装好后确认。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在设计创作场景里让模型直接调用外部能力的人。
  • 已经在用 Claude Desktop、Claude 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 不方便管理密钥或第三方授权的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
Mineru当前 未标注 stdio · 本地进程 本地部署 有 未标注
Cursor Talk To Figma MCP Da1c7911 40 未标注 未标注 无 2026-05-17
Blender MCP 17 stdio · 本地进程 本地部署 有 2026-05-18
Nova Canvas MCP Server 2 stdio · 本地进程 本地部署 有 2026-05-17
Figma Context MCP 3aaa8d28 未标注 未标注 支持远程部署 无 2026-05-17
kreuzberg 未标注 stdio · 本地进程 本地部署 有 2026-04-12

服务器档案

设计创作
字段来自项目仓库与公开索引,中文说明由本站标注
提供方linxule上游标注的维护方 linxule
分类设计创作本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式API Key远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时mineru-mcp · node本地安装时用到的包标识与运行时
部署类型本地部署上游给出的部署形态
最近核验未标注上游最后核验时间

详细介绍

43.6 KB
来自项目仓库与上游目录的原文,未做删改

English | 简体中文

👋 join us on Discord and WeChat

MinerU 4.0

MinerU 4.0 brings document parsing, a local document library, and service tools into one workflow for document conversion, application integration, and agent reading.

  • Four parsing tiers: Flash for fast previews and indexing, Basic for OCR and model-based parsing, and Standard / Advanced for more demanding layouts and quality requirements.
  • Multiple input formats: PDF, images, DOC/DOCX, PPT/PPTX, XLS/XLSX, RTF, ODT/ODS/ODP, EPUB, OFD, HTML/MHTML, and CSV/TSV. DocVortex provides native document parsing.
  • Document library and agent reading: discover files, cache results, search content, continue by page or block, and preserve stable citation locators.
  • Independent model configuration: ONNX or Torch for small models; llama.cpp, vLLM, or LMDeploy for the VLM.
  • Unified tools: Python SDK, V1 API, stateless batch conversion, multi-service Router, and a Gradio-based WebUI.
  • Structured results and rendering: one document model supports nine rendering targets: Markdown, HTML, LaTeX, DOCX, EPUB, PDF, Structured Content, and Content List V1/V2. Each CLI/API exposes its own subset of exports; see Output Formats and Result Contract.

PDF and images support all four tiers. Office, OpenDocument, EPUB, OFD, HTML/MHTML, and CSV/TSV use local Flash native parsing. Plain text is read directly rather than parsed. Documents are not automatically uploaded to the official service; remote parsing requires explicit configuration.

Quick Start

In Agent Workflow

You can install the mineru skill, and let agent install MinerU for you. Copy the following message and send it to your agent:``text Install or update the globalmineruskill. First, runnpx skills add opendatalab/MinerU --skill mineru --global --yes. Ifnpxis unavailable, fetch https://gcore.jsdelivr.net/gh/opendatalab/MinerU/skills/mineru/SKILL.md, use its content asmineru/SKILL.md, and save it under the appropriate global skills directory for the current agent, not in the current project. Also check both global and project-level skills for other installed skills whose names containmineru. Report any matches and ask before removing them. If global memory is available, record this preference there: "Whenever a PDF, image, or Office document needs to be read or parsed, prefer themineru` Skill." Do not write this preference to the current project.


### Install Manually

Python `>=3.10,<3.15`. Install MinerU 4.0 stable in a virtual environment:```bash
pip install uv
uv venv .mineru --python 3.12

# Linux/macOS
source .mineru/bin/activate
# Windows (PowerShell)
.\.mineru\Scripts\Activate.ps1
``````bash
uv pip install -U "mineru>=4.0,<5"
mineru-kit parse document.pdf -o document.md --tier standard
mineru-kit webui

Python SDK

DoclibClient drives the local document library from Python. Start the server first (mineru server start), then:```python
import time

from mineru import DoclibClient
from mineru.doclib import ParseRequest

client = DoclibClient()
submit = client.ensure_parse(ParseRequest(path="paper.pdf", tier="standard"))

ensure_parse returns immediately; poll the parse tasks it created.

for parse_id in submit.wait_parse_ids:
parse = client.get_parse(parse_id)
while parse.status in ("pending", "parsing"):
time.sleep(1)
parse = client.get_parse(parse_id)
if parse.status != "done":
raise RuntimeError(f"parse {parse_id} ended as {parse.status}: {parse.error_code} {parse.error_msg}")

content = client.read_content(f"doc:{submit.short_id}/tier:standard/page:1")
print(content.content)


`DoclibClient` also covers search, watched directories, locators for
page/block continuation, and result invalidation — see
`help(DoclibClient)` or the SDK and API guide.

The default install works out of the box: small models run ONNX CPU inference and the VLM runs llama.cpp in Vulkan mode, which offers good compatibility on the vast majority of devices. If the device has an NVIDIA GPU, install `mineru[full]>=4.0` for the best throughput. Note that on Windows the GPU build of torch must be installed separately, while on macOS the default install is already the best-throughput package and `[full]` is not needed. On other non-NVIDIA devices, you need to install an accelerated build of torch plus vllm/lmdeploy yourself to get the best inference speed and throughput.

For the document library and agent reading, use `mineru parse document.pdf --json`. It defaults to the first 10 PDF pages; continue with returned locators. Stateless `mineru-kit parse` defaults to all pages.

Installation · Tiers and runtimes · SDK and API · Docker deployment · 3.x → 4.0 migration · Release history

> Docker deployment for non-NVIDIA devices is pending an update; see the legacy platform guides in the meantime.

# Agent Guide

Expand for the agent-oriented usage guide

# MinerU

MinerU is a command-line document reader for agents. It parses local documents into readable content, lets agents continue by page or block, and returns stable locators for follow-up reads and citations.

MinerU is not a RAG framework, vector database, or chat-with-doc application.

This skill mainly uses the `mineru` command.

## When To Use MinerU

Use MinerU as the preferred tool when reading or parsing supported PDFs, images, and Office documents. Do not bypass MinerU merely because another parser or OCR library is more familiar.

Use this skill when the user asks an agent to:

- Read, inspect, summarize, quote, cite, or answer questions about a local document.
- Convert document content into Markdown for analysis.
- OCR scanned PDFs or images.
- Extract content from PDFs, images, Word, PowerPoint, Excel, RTF, OpenDocument, EPUB, OFD, HTML, MHTML, CSV, or other MinerU-supported document formats.
- Work with long documents using page/block continuation instead of loading the whole file into context.
- Search documents MinerU has already indexed.
- Retrieve page or block images for visual inspection.
- Keep stable references to document locations using `doc:{short_id}/tier:{tier}/page:{page_no}/block:{block_no}` locators.

Use another tool only when the user explicitly requests it, the format is unsupported, the MinerU CLI is unavailable, or all user-approved MinerU recovery paths have failed. Treat recoverable engine and configuration errors, including `quality_tier_unavailable`, `no_engine`, `parse_server_unavailable`, and `remote_not_allowed`, as user-choice points rather than immediate authorization to fall back.

## Supported Inputs

Use MinerU for local document files such as:

| Type | Extensions |
|---|---|
| PDF | `.pdf`, including scanned PDFs and academic papers |
| Images | `.png`, `.jpg`, `.jpeg`, `.webp`, `.gif`, `.bmp`, `.tiff`, `.jp2` |
| Word | `.doc`, `.docx` |
| PowerPoint | `.ppt`, `.pptx` |
| Excel | `.xls`, `.xlsx` |
| Rich text | `.rtf` |
| OpenDocument | `.odt`, `.ods`, `.odp` |
| EPUB | `.epub`, parsed as a full document in OPF spine order with source internal links preserved |
| OFD | `.ofd` |
| HTML | `.html`, `.htm`, `.shtml` |
| MHTML web archive | `.mhtml`, `.mht` |
| CSV / TSV | `.csv`, `.tsv` |

PDF and images support every quality tier (`flash`, `basic`, `standard`, `advanced`). Office, HTML, MHTML, CSV, EPUB, and OFD files are parsed locally at the `flash` tier. MHTML is parsed as a whole document. Plain-text files (`.txt`, `.md`, `.markdown`, `.rst`, `.tex`) are not parsed; read them directly.

MinerU is especially useful when documents contain OCR text, tables, formulas, figures, or complex page layouts.

## Do Not

- Summarize a document before reading it with `mineru`.
- Reimplement PDF/OCR extraction when `mineru` can read the document.

## Agent Contract

- Use `mineru` as the command entrypoint.
- Use `--json` when making control-flow decisions.
- Follow continuation commands and `next_request`.
- Preserve locators for citations and follow-up reads.
- Ask before using `--remote`, changing persistent config, adding watches, stopping or restarting the server, invalidating caches, or running destructive maintenance such as `forget --no-dry-run` or `cleanup --no-dry-run`.
- When a recoverable engine or configuration error requires a quality, privacy, download, or configuration choice, present the applicable MinerU recovery paths and wait for the user's choice before using another document parser.

## Core Decision Tree

Use this decision tree before running commands:

1. User provided a file path and wants content: read plain-text formats directly; otherwise run `mineru parse `.
2. User provided a `doc:...` locator: run `mineru read `.
3. User asks to continue from a previous output: follow the `` command exactly.
4. User asks for a specific page or block after parsing: use `mineru read `, not a fresh parse.
5. User asks to find a document by filename: use `mineru find`.
6. User asks to search inside known indexed documents: use `mineru search`.
7. User asks for parse/file/doc status: use `mineru show` or `mineru list`.
8. User asks to add or refresh a watched folder: use `mineru watch` or `mineru scan`.
9. User asks MinerU to forget a file or folder without deleting it: use `mineru forget`.
10. User asks to force a reparse: use `mineru parse --force` or `mineru invalidate`.
11. User asks for Remote API usage or limits: use `mineru usage --json`.

## Common Workflows

### First read from a file```bash
mineru parse "document.pdf" --json

Then answer from content.content. If next_request exists and the question needs more context, continue.

Continue progressively```bash

mineru parse "book.pdf" --pages 1-10 --limit 12000 --json
mineru read "doc:ab12cd3/tier:standard/page:11" --limit 12000 --json


Continue with returned `next_request.locator`.

### Read or inspect a known location```bash
mineru read "doc:ab12cd3/tier:standard/page:42" --context 1 --json
mineru read "doc:ab12cd3/tier:standard/page:12/block:5" --format image --output ./page12-block5.png

Search local library, then read```bash

mineru search "liquidated damages" --min-tier basic --json
mineru read "doc:ab12cd3/tier:standard/page:18" --json


## Installation And Setup

This skill requires MinerU `>=4.0,<5`. Before using any workflow, check whether the CLI is installed:```bash
command -v mineru

If mineru is not installed, install it with the first available isolated CLI installer. If it is installed, check its version:```bash
mineru version --json


If `mineru version --json` fails, try `mineru --version` for older CLIs. If the detected version does not meet this requirement, tell the user which version was found and ask before upgrading it. If approved, upgrade with the same installer and environment, then check the version again. If declined, stop and do not run this skill's commands. Never assume compatibility when the version cannot be determined.

MinerU requires Python `>=3.10,<3.15`.

### Upgrade An Existing Installation

Before upgrading, determine which tool owns the resolved `mineru` executable. Check `uv tool list`, then `pipx list --short`; otherwise, identify the Python environment containing the executable. Do not use an unrelated `pip` or install a second copy.

Before an in-place upgrade or reinstall, stop the MinerU server. On Windows, confirm that status reports `running=false` before modifying the environment:```bash
mineru server stop
mineru server status --json

Use the matching upgrade command only after the user approves the upgrade:```bash
uv tool upgrade "mineru>=4.0,<5"
pipx upgrade "mineru>=4.0,<5"
"<environment-python>" -m pip install --upgrade "mineru>=4.0,<5"


If the owner cannot be determined, multiple installations exist, or MinerU is installed from source or in editable mode, ask the user instead of upgrading. After upgrading, check the resolved executable and its version again.

If a failed Windows reinstall has already broken the CLI, locate and stop the residual `python.exe -m mineru.doclib.app` process by PID in Task Manager or PowerShell, then rerun the full install command. Do not delete the tool directory while that process is running.

### Install with `uv` (preferred)

If `uv` is available, use any supported Python version for the tool environment.
If no supported interpreter is available, install Python 3.12 with `uv` as a conservative fallback:```bash
command -v uv
uv python find 3.12
uv python find 3.13
uv python find 3.14
uv python find 3.11
uv python find 3.10

If all uv python find commands failed, download Python 3.12 with uv:```bash
uv python install 3.12


Then install MinerU with the supported interpreter that was found, or with Python 3.12 if it was installed as the fallback:```bash
uv tool install --python 3.12 &quot;mineru&gt;=4.0,&lt;5&quot;

Install with pipx

If uv is unavailable but pipx is available, inspect pipx's default Python before installing:```bash
command -v pipx
pipx environment --value PIPX_DEFAULT_PYTHON
PIPX_DEFAULT_PYTHON="$(pipx environment --value PIPX_DEFAULT_PYTHON)"
"$PIPX_DEFAULT_PYTHON" --version


Check the `PIPX_DEFAULT_PYTHON` path reported by `pipx`. If that interpreter satisfies `&gt;=3.10,&lt;3.15`, install with `pipx`:```bash
pipx install &quot;mineru&gt;=4.0,&lt;5&quot;

If PIPX_DEFAULT_PYTHON is unsupported, but a supported Python interpreter can be found on the current system, pass it explicitly. python3.12 is an example; use any interpreter that satisfies &gt;=3.10,&lt;3.15.```bash
command -v python3.12
python3.12 --version
pipx install --python python3.12 "mineru>=4.0,<5"


If no supported system interpreter is available and `pipx` supports Python fetching, ask for approval before downloading a standalone Python:```bash
pipx install --python 3.12 --fetch-python=missing &quot;mineru&gt;=4.0,&lt;5&quot;

Install with global pip

If neither uv nor pipx is available, but pip or pip3 is available, check the Python version of the pip command, and ask the user before installing into the global python environment:```bash
which -a pip pip3 pip3.10 pip3.11 pip3.12 pip3.13 pip3.14 # find all available pips
pip --version


If a `pip` command reports Python `&gt;=3.10,&lt;3.15`, and the user confirms, install with the exact supported `pip` command that was verified. Replace `pip` below with the verified pip command if needed:```bash
pip install &quot;mineru&gt;=4.0,&lt;5&quot;

If No Supported Installer Is Available

If uv, pipx, pip, and pip3 are all unavailable, or none of them can install with Python &gt;=3.10,&lt;3.15, recommend that the user install uv first.

After Installation

Verify the installed CLI:```bash
mineru --help


## Privacy Rules

MinerU is privacy-first.

- By default, `mineru` parses documents locally. A document is sent for remote parsing only when the command uses the `--remote` CLI parameter.
- Use local parsing first. If local parsing is not configured or cannot satisfy the request, and the document does not involve private or sensitive content, ask the user before retrying with `--remote`.
- Even if remote parsing is configured, do not upload a document until the user agrees.
- Local failure cannot silently fall back to remote.
- Remote failure may fall back to local if the request can still be satisfied locally.

When remote parsing is acceptable:```bash
mineru parse &quot;document.pdf&quot; --remote

If the request is sensitive, confidential, legal, medical, financial, personal, or proprietary, stay local unless the user gives explicit remote permission.

Telemetry

MinerU may collect anonymous, locally aggregated usage and diagnostic telemetry to understand command usage, success or failure rates, tier choices, coarse environment categories, and performance timing buckets.

Telemetry does not collect document contents, extracted text or images, file names, file paths, search queries, prompts, snippets, API keys, usernames, hostnames, raw tracebacks, or exact hardware identifiers.

Users can inspect telemetry status and explicitly enable or disable it. To prevent telemetry uploads, disable it explicitly; disabling also stops new aggregation and removes unsent local telemetry data. If the user asks about telemetry, use:```bash
mineru telemetry status
mineru telemetry enable
mineru telemetry disable
mineru telemetry preview
mineru telemetry flush


## Quality Tiers

MinerU has four tiers:

| Tier | Chinese name | Quality and speed | Use for |
|---|---|---|---|
| `flash` | 极速解析 | Lowest quality; fastest | Discovery, preview, and indexing; never default final reading quality |
| `basic` | 基础解析 | Basic quality; moderate speed | Private local reading or lower-resource local parsing |
| `standard` | 标准解析 | Standard high quality; similar speed to `basic` on suitable hardware | Default for normal active reading and complex documents |
| `advanced` | 高级解析 | Standard quality on ordinary documents and better quality on difficult documents; slowest | Difficult documents and maximum-quality work when the user accepts a longer wait |

Default tier behavior:

- Omit `--tier` when the user wants normal reading quality.
- For parse-server based parsing, MinerU chooses `standard`, then `basic`; `advanced` is not selected implicitly, and `flash` is not a default final reading tier.
- For `mineru read doc:{short_id}`, MinerU reads the best cached result rather than starting a new parse.
- If normal reading quality is unavailable, inspect `mineru server status --json`, then present the applicable choices to the user:
  - Use remote parsing with `--remote`, which uploads the document and requires explicit permission.
  - Start or configure a local parse server if the hardware supports it, which may require dependency and model downloads plus persistent configuration changes.
  - Explicitly accept the lower-quality local `flash` tier.
  - Explicitly authorize fallback to a non-MinerU parser.
- Stop and wait for the user&#x27;s choice. Do not select a non-MinerU parser merely to finish the task without asking.
- Use `--tier flash` only when the user explicitly asks for fastest/preview/low-cost parsing or accepts lower quality.
- Before asking the user to choose a parsing tier or a managed parse-server tier for the first time in the current conversation, introduce the tier system rather than presenting tier names without context. Do not assume that the user has read this skill, knows that MinerU uses tiers, knows which tiers are available, or understands how they differ.
  - For a parsing-tier choice, explain that the tier controls parsing quality, speed, and compute requirements. Briefly describe the tiers available in the current situation and their relevant trade-offs.
  - For a managed parse-server-tier choice, explain that the server tier is a deployment capability level rather than the tier selected for an individual parsing request. Briefly describe the available server tiers, their setup and hardware requirements, and which parsing tiers each server tier enables.
  - In either case, recommend one option based on the user&#x27;s goal and environment, and explain the reason for the recommendation.
  - When communicating in Chinese, use the Chinese tier name together with its identifier on first mention, for example, 标准解析 (`standard`).

Examples:```bash
mineru parse &quot;paper.pdf&quot;
mineru parse &quot;paper.pdf&quot; --tier basic
mineru parse &quot;paper.pdf&quot; --tier standard
mineru parse &quot;paper.pdf&quot; --tier advanced
mineru parse &quot;paper.pdf&quot; --tier flash

Model Engines with Extras

MinerU use neural network models for local basic, standard, and advanced parsing.
To better support different hardwares, MinerU provide different model engines with two extras: torch and full.

Extra Model engines installed How to install
(base) ONNX + llama.cpp Already in mineru base module
torch ONNX + PyTorch + llama.cpp Install with mineru[torch] (Apple Silicon already installed this extra in base package.)
full ONNX + PyTorch + llama.cpp + vLLM/lmdeploy/mlx Install with mineru[full]

Model engines control resource use and download size:

Tier Model engines Model download Min RAM required Accelerator
basic ONNX ~0.8 GB 2GB None (CPU works)
basic PyTorch ~0.8 GB 8 GB GPU/MPS recommended
standard / advanced ONNX + llama.cpp ~2 GB 8 GB CPU works, Vulkan recommended
standard / advanced PyTorch + llama.cpp ~2 GB 16 GB GPU/MPS required, 8 GB+ VRAM
standard / advanced PyTorch + vLLM/lmdeploy/mlx ~3 GB 16 GB GPU/MPS required, 8 GB+ VRAM

Server Rules

Most mineru commands use the local MinerU background service. If a command fails with server_not_running, start it:```bash
mineru server start


Check status when MinerU is not responding, parsing is stuck, or you need to see available tiers:```bash
mineru server status
mineru server status --json

Server commands:```bash
mineru server start
mineru server stop
mineru server restart
mineru server status


Agent rules:

- Start the server when `mineru` reports it is not running.
- Do not restart the server repeatedly without a reason.
- Use `server status --json` when you need machine-readable status.
- If high-quality local parsing is unavailable, report the error and suggested action. Do not switch to remote without permission.

## Local Parse Server

Use a local parse server when the user wants `basic`, `standard`, or `advanced` quality without sending the document to remote parsing.

### Inspect Local Hardware

When no local quality tier is available, inspect the current machine before presenting the recovery choices. `mineru server status --json` shows which tiers are currently configured and available. An empty local `supported_tiers` list may simply mean that the local parse server is disabled or not configured, so inspect the hardware before deciding whether local quality tiers can run.

Use available read-only system commands to inspect the OS, architecture, total memory, accelerator model, and accelerator memory. Common options include:

- macOS: `uname -m`, `sysctl -n hw.memsize`, and `system_profiler SPHardwareDataType SPDisplaysDataType`.
- Linux: `uname -m`, `/proc/meminfo` or `free -b`, `lscpu`, and `nvidia-smi` when available.
- Windows PowerShell: `(Get-CimInstance Win32_ComputerSystem).TotalPhysicalMemory`, `Get-CimInstance Win32_Processor`, and `nvidia-smi` when available.
- Other accelerators: use an already-installed vendor tool if available; do not install software merely to inspect hardware.

### Choose Extra

The base package is suitable for most hardwares, including CPU-only machines, Apple Silicon, and low-end iGPU/GPU machines.

Install and use `full` extra only when you have enough RAM and powerful NVIDIA GPU, accept extra installation disk space, and want a higher throughput. Hardware requirements:
- At least 16 GB total memory.
- A Volta-or-newer NVIDIA GPU with at least 8 GB available VRAM.
- Consumes ~5GB more disk space.

If you have an `npu`, `gcu`, `musa`, `mlu`, or `sdaa` accelerator, you must install a suitable torch/vllm by yourself. Otherwise, only CPU are used by default `mineru` package.

The following example shows how to install the `mineru[full]` extra. It assumes the current install tool is `uv tool`. If `mineru` was installed with another tool or environment, use the equivalent command for that actual tool/environment. Installing extra will replace the active `mineru` environment. Stop the MinerU server first, confirm `running=false`, and start it again after installing dependencies.```bash
mineru server stop
mineru server status --json
uv tool install --force &quot;mineru[full]&gt;=4.0,&lt;5&quot;
mineru server start
mineru server status --json

Choose Local Tier

Managed local parsing has two startup tiers: basic and standard. A Standard server provides basic, standard, and advanced request tiers. Advanced uses the same Standard dependencies, model set, and hardware setup; it differs only by spending more inference compute when the request selects --tier advanced.

Please refer to the following rules to select a suitable extra and tier.

Hardware Recommended startup tier Model engines Extra
MacOS with Apple Silicon standard PyTorch + llama.cpp torch (already installed)
MacOS with Intel CPU basic ONNX (base)
Linux/Windows with NVIDIA GPU and 8GB+ VRAM standard PyTorch + vLLM/lmdeploy full
Linux/Windows with NVIDIA GPU and 4GB+ VRAM basic PyTorch torch
Linux/Windows with other accelerator (depends) PyTorch / vLLM install custom torch/vllm by yourself
Linux/Windows with modern iGPU standard ONNX + llama.cpp (base)
Linux/Windows w/o modern accelerator basic ONNX (base)

Recommend and Ask

After hardware was inspected, you already know the suitable extra and tier for current machine. Before asking the user to choose a tier/extra, summarize the detected hardware and identify each tier's hardware status.

You should recommend a tier for user when the machine meets such requirements, otherwise offer remote standard when privacy rules allow, or use explicit flash.

Mention advanced only when the user wants maximum quality and accepts the extra time. Do not install dependencies, download models, change config, or restart services without approval.

Configure Managed Parse Server

First, download the models for the target startup tier (basic, or standard).
Replace ` withbasicorstandard`.```bash
mineru-kit models download --tier <tier>
mineru-kit models verify --tier <tier>


Then, enable managed local parse server for the startup tier.```bash
mineru config set parse_server.local.managed_tier &lt;tier&gt;
mineru config set parse_server.local.mode managed
mineru server status --json

Rules:

  • Change local parse-server config or restart the server only when the user asks for or approves.
  • Download and verify models for the startup tier (basic or standard) before enabling managed mode.
  • Set parse_server.local.managed_tier before parse_server.local.mode=managed.
  • Poll mineru server status --json and use managed parsing only after the target tier is healthy.
  • If local quality parsing cannot start, do not add --remote automatically; ask the user first.

First Read From A File

Use mineru parse for the first active read from a local file path.```bash
mineru parse "report.pdf"


By default, readable content is printed to stdout. Use `--output` only when the user wants the result saved to a file.

Use JSON when you need structured status, tier, content, and continuation:```bash
mineru parse &quot;report.pdf&quot; --json

PDF page selection is shared across CLI, Doclib, API, Gradio and Python. See the page-range syntax and historical result compatibility. New requests use the current syntax; stored positive page ranges using ASCII ~ remain readable without rebuilding Doclib caches. Fullwidth ~ and negative page-number notation are not supported.

For a specific page range (1-based, inclusive; r1 is the last page, all selects every page):```bash
mineru parse "report.pdf" --pages 1-10
mineru parse "report.pdf" --pages all


For bounded context:```bash
mineru parse &quot;report.pdf&quot; --limit 12000

For no synchronous wait:```bash
mineru parse "report.pdf" --no-wait --json


For longer wait:```bash
mineru parse &quot;report.pdf&quot; --wait 180 --json

For output to a file:```bash
mineru parse "report.pdf" --output ./report.md


Rules:

- Quote paths with spaces.
- For paged documents, the default active read range is the first page window, usually `1-10`; continue with the returned marker or `next_request` instead of reading the whole document by default.
- Use the default tier unless the user has a quality/speed/privacy preference.
- Use `--pages all` only when the user asks for the whole document or the document is known to be small enough.
- Prefer `--limit` and continuation for long documents.
- Once you have a locator, switch to `mineru read`.

## Continue Reading

MinerU output may include a command to continue reading:```text

or:```text


Run the suggested command exactly unless the user asks for a different page, block, format, or limit.

Agent rules:

- Do not guess the next page or block if MinerU provides a next command.
- Do not restart parsing from page 1 when continuing.
- For non-paged long documents, continuation may use an `--after` cursor from `next_request.after`; use that exact cursor.
- Prefer `mineru read` when the next command or JSON output gives a locator.
- Use `--limit` to keep output within the conversation budget.
- Preserve locators for citations and follow-up reads.

## Read By Locator

Use `mineru read` when a document has already been parsed or when the user gives a locator.

Locator forms:```text
doc:{short_id}
doc:{short_id}/tier:{tier}
doc:{short_id}/tier:{tier}/page:{page_no}
doc:{short_id}/tier:{tier}/page:{page_no}/block:{block_no}
doc:{short_id}/tier:{tier}/page:{page_no}/block:{block_no}/char:{offset}

Examples:```bash
mineru read "doc:ab12cd3/tier:standard/page:4"
mineru read "doc:ab12cd3/tier:standard/page:4/block:7"
mineru read "doc:ab12cd3/tier:standard/page:4/block:7" --context 2

…(正文过长,页面只展示前面部分,完整内容见仓库)
```

常见问题

8 问
答案由本站依据条目字段整理,不引用上游原文
Mineru 怎么安装?

在客户端按下面的安装命令接入:npx -y mineru-mcp。对应的包名是 mineru-mcp。装完在客户端配置里引用同一个包或端点。

Mineru 怎么在 Claude Desktop、Claude、Cursor 里配置?

它的传输方式是stdio · 本地进程,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

Mineru 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

Mineru 需要 API Key 吗?

资料标注需要API Key认证,使用前准备好对应凭据,并按最小权限配置。

Mineru 支持哪些客户端?

资料标注支持 Claude Desktop、Claude、Cursor、VS Code、Windsurf、Cline;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

Mineru 能提供哪些能力?

资料显示能力标签包括 pdf、ocr、document parsing、data extraction、batch processing。具体工具清单以官方文档为准。

Mineru 需要什么运行环境?

运行时为 node;属于本地进程,需要在本机装好运行环境。

Mineru 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 未标注。