linxule/mineru-mcp

MCP server and mineru-cloud CLI for the MinerU document
parsing API, with complete artifact retention, durable operations, and portable
PDF bundles.
Durable operations and bundles in this checkout are unreleased. The published
mineru-mcp@1.2.0 does not include them; npm users need a release containing these
changes.
Features
- **VLM model** — Document parsing with a vision-language model
- **Pipeline model** — Document parsing with the pipeline model
- **Local file upload** — Upload files from disk for batch parsing
- **Batch processing** — Submit multiple documents in one request
- **Download & rename** — Extract markdown with original filenames
- **Page ranges** — Extract specific pages only
- **Long documents** — mineru_parse_long submits page-range slices and mineru_merge_slices stitches
- **CLI twin** — mineru-cloud calls the same tools from a shell
- **Language and OCR options** — Select a language and enable OCR for the pipeline model
Tools
| Tool | Description |
|------|-------------|
| mineru_parse | Parse a document URL |
| mineru_status | Check task progress, get download URL |
| mineru_batch | Parse multiple URLs |
| mineru_batch_status | Get batch results with pagination |
| mineru_upload_batch | Upload local files for batch parsing |
| mineru_download_results | Retain complete archives, inventory all members, and create named compatibility copies |
| mineru_parse_long | Submit a long document as a batch of page-range slices |
| mineru_merge_slices | Join available Markdown and retain immutable slice archives with explicit unknown page provenance |
| mineru_capabilities | Read locally known capabilities; explicit refresh performs discovery |
| mineru_submit | Submit with a durable local journal and duplicate-request protection |
| mineru_operation_status | Read a recorded operation; explicit refresh checks remote status |
| mineru_resume | Continue safe recorded checkpoints |
| mineru_cancel | Stop local processing; remote cancellation is unsupported |
| mineru_bundle | Validate and return an operation's retained bundle |
Installation
Use Node.js 24 for new installations. Node.js 18+ remains
supported for compatibility. Cloud commands require a MinerU API key;
offline bundle creation requires no credentials.
Local output retention, bundles, and durable operations require macOS or Linux.
These paths use directory-bound filesystem operations and fail closed on Windows;
the Windows client configuration below does not imply local retention support.
CLI Install (one-liner)
Claude Desktop
Add to your claude_desktop_config.json:
| OS | Config path |
|----|-------------|
| macOS | ~/Library/Application Support/Claude/claude_desktop_config.json |
| Windows | %APPDATA%\Claude\claude_desktop_config.json |
| Linux | ~/.config/Claude/claude_desktop_config.json |
VS Code
Add to .vscode/mcp.json (workspace) or open Command Palette > MCP: Open User Configuration (global):
> **Note**: VS Code uses "servers" as the top-level key, not "mcpServers". Other VS Code forks (Trae, Void, PearAI, etc.) typically use this same format.
Cursor
Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project):
Windsurf
Add to ~/.codeium/windsurf/mcp_config.json (Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json):
Cline
Open MCP Servers icon in Cline panel > Configure > Advanced MCP Settings, then add:
Cherry Studio
In Settings > MCP Servers > Add Server, set Type to STDIO, Command to npx, Args to -y mineru-mcp, and add environment variable MINERU_API_KEY. Or paste in JSON/Code mode:
Witsy
In Settings > MCP Servers, add a new server with Type: stdio, Command: npx, Args: -y mineru-mcp, and set environment variable MINERU_API_KEY to your API key.
Codex CLI (TOML config)
Alternatively, edit ~/.codex/config.toml directly:
Gemini CLI (JSON config)
Alternatively, edit ~/.gemini/settings.json directly:
Windows
On Windows, npx requires a shell wrapper. Replace "command": "npx" with:
For CLI tools on Windows:
ChatGPT
ChatGPT only supports remote MCP servers over HTTPS — local stdio servers like this one are not directly supported. You would need to deploy behind a public URL with HTTP transport.