MCP server for MinerU document parsing API — extract text, tables, and formulas from PDFs, DOCs, and images. - 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 - Download & rename — Extract markdown with original filenames - Pa
Add this skill
npx mdskills install linxule/mineru-mcpComprehensive MCP server with well-documented API tools for document parsing and batch processing
1# mineru-mcp23MCP server for [MinerU](https://mineru.net) document parsing API — extract text, tables, and formulas from PDFs, DOCs, and images.45## Features67- **VLM model** — 90%+ accuracy for complex documents8- **Pipeline model** — Fast processing for simple documents9- **Local file upload** — Upload files from disk for batch parsing10- **Batch processing** — Parse up to 200 documents at once11- **Download & rename** — Extract markdown with original filenames12- **Page ranges** — Extract specific pages only13- **109 language OCR** support14- **Optimized for Claude Code** — 73% token reduction vs alternatives1516## Tools1718| Tool | Description |19|------|-------------|20| `mineru_parse` | Parse a document URL |21| `mineru_status` | Check task progress, get download URL |22| `mineru_batch` | Parse multiple URLs (max 200) |23| `mineru_batch_status` | Get batch results with pagination |24| `mineru_upload_batch` | Upload local files for batch parsing |25| `mineru_download_results` | Download results as named markdown files |2627## Installation2829Requires [Node.js](https://nodejs.org/) 18+ and a [MinerU API key](https://mineru.net).3031### CLI Install (one-liner)3233```bash34# Claude Code35claude mcp add mineru-mcp -e MINERU_API_KEY=your-api-key -- npx -y mineru-mcp3637# Codex CLI (OpenAI)38codex mcp add mineru --env MINERU_API_KEY=your-api-key -- npx -y mineru-mcp3940# Gemini CLI (Google)41gemini mcp add -e MINERU_API_KEY=your-api-key mineru npx -y mineru-mcp42```4344### Claude Desktop4546Add to your `claude_desktop_config.json`:4748| OS | Config path |49|----|-------------|50| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |51| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |52| Linux | `~/.config/Claude/claude_desktop_config.json` |5354```json55{56 "mcpServers": {57 "mineru": {58 "command": "npx",59 "args": ["-y", "mineru-mcp"],60 "env": {61 "MINERU_API_KEY": "your-api-key"62 }63 }64 }65}66```6768### VS Code6970Add to `.vscode/mcp.json` (workspace) or open Command Palette > `MCP: Open User Configuration` (global):7172```json73{74 "servers": {75 "mineru": {76 "command": "npx",77 "args": ["-y", "mineru-mcp"],78 "env": {79 "MINERU_API_KEY": "your-api-key"80 }81 }82 }83}84```8586> **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.8788### Cursor8990Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project):9192```json93{94 "mcpServers": {95 "mineru": {96 "command": "npx",97 "args": ["-y", "mineru-mcp"],98 "env": {99 "MINERU_API_KEY": "your-api-key"100 }101 }102 }103}104```105106### Windsurf107108Add to `~/.codeium/windsurf/mcp_config.json` (Windows: `%USERPROFILE%\.codeium\windsurf\mcp_config.json`):109110```json111{112 "mcpServers": {113 "mineru": {114 "command": "npx",115 "args": ["-y", "mineru-mcp"],116 "env": {117 "MINERU_API_KEY": "your-api-key"118 }119 }120 }121}122```123124### Cline125126Open MCP Servers icon in Cline panel > Configure > Advanced MCP Settings, then add:127128```json129{130 "mcpServers": {131 "mineru": {132 "command": "npx",133 "args": ["-y", "mineru-mcp"],134 "env": {135 "MINERU_API_KEY": "your-api-key"136 }137 }138 }139}140```141142### Cherry Studio143144In 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:145146```json147{148 "mineru": {149 "name": "MinerU",150 "command": "npx",151 "args": ["-y", "mineru-mcp"],152 "env": {153 "MINERU_API_KEY": "your-api-key"154 },155 "isActive": true156 }157}158```159160### Witsy161162In 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.163164### Codex CLI (TOML config)165166Alternatively, edit `~/.codex/config.toml` directly:167168```toml169[mcp_servers.mineru]170command = "npx"171args = ["-y", "mineru-mcp"]172173[mcp_servers.mineru.env]174MINERU_API_KEY = "your-api-key"175```176177### Gemini CLI (JSON config)178179Alternatively, edit `~/.gemini/settings.json` directly:180181```json182{183 "mcpServers": {184 "mineru": {185 "command": "npx",186 "args": ["-y", "mineru-mcp"],187 "env": {188 "MINERU_API_KEY": "your-api-key"189 }190 }191 }192}193```194195### Windows196197On Windows, `npx` requires a shell wrapper. Replace `"command": "npx"` with:198199```json200{201 "command": "cmd",202 "args": ["/c", "npx", "-y", "mineru-mcp"],203 "env": {204 "MINERU_API_KEY": "your-api-key"205 }206}207```208209For CLI tools on Windows:210211```bash212claude mcp add mineru-mcp -e MINERU_API_KEY=your-api-key -- cmd /c npx -y mineru-mcp213codex mcp add mineru --env MINERU_API_KEY=your-api-key -- cmd /c npx -y mineru-mcp214```215216### ChatGPT217218ChatGPT 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.219220## Configuration221222| Environment Variable | Default | Description |223|---------------------|---------|-------------|224| `MINERU_API_KEY` | (required) | Your MinerU API Bearer token |225| `MINERU_BASE_URL` | `https://mineru.net/api/v4` | API base URL |226| `MINERU_DEFAULT_MODEL` | `pipeline` | Default model: `pipeline` or `vlm` |227228Get your API key at [mineru.net](https://mineru.net)229230## Usage231232### Parse a single URL233234```typescript235mineru_parse({236 url: "https://example.com/document.pdf",237 model: "vlm", // optional: "pipeline" (default) or "vlm" (90% accuracy)238 pages: "1-10,15", // optional: page ranges239 ocr: true, // optional: enable OCR (pipeline only)240 formula: true, // optional: formula recognition241 table: true, // optional: table recognition242 language: "en", // optional: language code243 formats: ["html"] // optional: extra export formats244})245```246247### Check task progress248249```typescript250mineru_status({251 task_id: "abc-123",252 format: "concise" // optional: "concise" (default) or "detailed"253})254```255256**Concise output**: `done | abc-123 | https://cdn-mineru.../result.zip`257258### Batch parse URLs259260```typescript261mineru_batch({262 urls: ["https://example.com/doc1.pdf", "https://example.com/doc2.pdf"],263 model: "vlm"264})265```266267### Check batch progress268269```typescript270mineru_batch_status({271 batch_id: "batch-123",272 limit: 10, // optional: max results (default: 10)273 offset: 0, // optional: skip first N results274 format: "concise" // optional: "concise" or "detailed"275})276```277278### Upload local files279280```typescript281mineru_upload_batch({282 directory: "/path/to/pdfs", // scan directory for supported files283 // OR284 files: ["/path/to/doc1.pdf", "/path/to/doc2.pdf"], // explicit file list285 model: "vlm", // optional286 formula: true, // optional287 table: true, // optional288 language: "en", // optional289 formats: ["html"] // optional290})291```292293Returns `batch_id` for tracking. Each file's original name is preserved via `data_id` (spaces become underscores).294295### Download results as markdown296297```typescript298mineru_download_results({299 batch_id: "batch-123", // from mineru_upload_batch or mineru_batch300 output_dir: "/path/to/output",301 overwrite: false // optional: overwrite existing files302})303```304305Output filenames are derived from `data_id` (e.g., `my_paper_title.md`). Spaces in original filenames become underscores.306307### Typical local file workflow308309```310mineru_upload_batch → mineru_batch_status (poll) → mineru_download_results311```312313## Supported Formats314315- PDF, DOC, DOCX, PPT, PPTX316- PNG, JPG, JPEG317318## Limits319320- Single file: 200MB max, 600 pages max321- Daily quota: 2000 pages at high priority322- Batch: max 200 files per request323324## License325326MIT327328## Links329330- [MinerU](https://mineru.net) — Document parsing service331- [MinerU GitHub](https://github.com/opendatalab/MinerU) — Open source version332- [MCP Specification](https://modelcontextprotocol.io) — Model Context Protocol333
Full transparency — inspect the skill content before installing.