{
  "markdown": "# mineru-mcp\n\nMCP server for [MinerU](https://mineru.net) document parsing API — extract text, tables, and formulas from PDFs, DOCs, and images.\n\n## Features\n\n- **VLM model** — 90%+ accuracy for complex documents\n- **Pipeline model** — Fast processing for simple documents\n- **Local file upload** — Upload files from disk for batch parsing\n- **Batch processing** — Parse up to 200 documents at once\n- **Download & rename** — Extract markdown with original filenames\n- **Page ranges** — Extract specific pages only\n- **109 language OCR** support\n- **Optimized for Claude Code** — 73% token reduction vs alternatives\n\n## Tools\n\n| Tool | Description |\n|------|-------------|\n| `mineru_parse` | Parse a document URL |\n| `mineru_status` | Check task progress, get download URL |\n| `mineru_batch` | Parse multiple URLs (max 200) |\n| `mineru_batch_status` | Get batch results with pagination |\n| `mineru_upload_batch` | Upload local files for batch parsing |\n| `mineru_download_results` | Download results as named markdown files |\n\n## Installation\n\nRequires [Node.js](https://nodejs.org/) 18+ and a [MinerU API key](https://mineru.net).\n\n### CLI Install (one-liner)\n\n```bash\n# Claude Code\nclaude mcp add mineru-mcp -e MINERU_API_KEY=your-api-key -- npx -y mineru-mcp\n\n# Codex CLI (OpenAI)\ncodex mcp add mineru --env MINERU_API_KEY=your-api-key -- npx -y mineru-mcp\n\n# Gemini CLI (Google)\ngemini mcp add -e MINERU_API_KEY=your-api-key mineru npx -y mineru-mcp\n```\n\n### Claude Desktop\n\nAdd to your `claude_desktop_config.json`:\n\n| OS | Config path |\n|----|-------------|\n| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |\n| Windows | `%APPDATA%\\Claude\\claude_desktop_config.json` |\n| Linux | `~/.config/Claude/claude_desktop_config.json` |\n\n```json\n{\n  \"mcpServers\": {\n    \"mineru\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mineru-mcp\"],\n      \"env\": {\n        \"MINERU_API_KEY\": \"your-api-key\"\n      }\n    }\n  }\n}\n```\n\n### VS Code\n\nAdd to `.vscode/mcp.json` (workspace) or open Command Palette > `MCP: Open User Configuration` (global):\n\n```json\n{\n  \"servers\": {\n    \"mineru\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mineru-mcp\"],\n      \"env\": {\n        \"MINERU_API_KEY\": \"your-api-key\"\n      }\n    }\n  }\n}\n```\n\n> **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.\n\n### Cursor\n\nAdd to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project):\n\n```json\n{\n  \"mcpServers\": {\n    \"mineru\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mineru-mcp\"],\n      \"env\": {\n        \"MINERU_API_KEY\": \"your-api-key\"\n      }\n    }\n  }\n}\n```\n\n### Windsurf\n\nAdd to `~/.codeium/windsurf/mcp_config.json` (Windows: `%USERPROFILE%\\.codeium\\windsurf\\mcp_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"mineru\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mineru-mcp\"],\n      \"env\": {\n        \"MINERU_API_KEY\": \"your-api-key\"\n      }\n    }\n  }\n}\n```\n\n### Cline\n\nOpen MCP Servers icon in Cline panel > Configure > Advanced MCP Settings, then add:\n\n```json\n{\n  \"mcpServers\": {\n    \"mineru\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mineru-mcp\"],\n      \"env\": {\n        \"MINERU_API_KEY\": \"your-api-key\"\n      }\n    }\n  }\n}\n```\n\n### Cherry Studio\n\nIn 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:\n\n```json\n{\n  \"mineru\": {\n    \"name\": \"MinerU\",\n    \"command\": \"npx\",\n    \"args\": [\"-y\", \"mineru-mcp\"],\n    \"env\": {\n      \"MINERU_API_KEY\": \"your-api-key\"\n    },\n    \"isActive\": true\n  }\n}\n```\n\n### Witsy\n\nIn 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.\n\n### Codex CLI (TOML config)\n\nAlternatively, edit `~/.codex/config.toml` directly:\n\n```toml\n[mcp_servers.mineru]\ncommand = \"npx\"\nargs = [\"-y\", \"mineru-mcp\"]\n\n[mcp_servers.mineru.env]\nMINERU_API_KEY = \"your-api-key\"\n```\n\n### Gemini CLI (JSON config)\n\nAlternatively, edit `~/.gemini/settings.json` directly:\n\n```json\n{\n  \"mcpServers\": {\n    \"mineru\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mineru-mcp\"],\n      \"env\": {\n        \"MINERU_API_KEY\": \"your-api-key\"\n      }\n    }\n  }\n}\n```\n\n### Windows\n\nOn Windows, `npx` requires a shell wrapper. Replace `\"command\": \"npx\"` with:\n\n```json\n{\n  \"command\": \"cmd\",\n  \"args\": [\"/c\", \"npx\", \"-y\", \"mineru-mcp\"],\n  \"env\": {\n    \"MINERU_API_KEY\": \"your-api-key\"\n  }\n}\n```\n\nFor CLI tools on Windows:\n\n```bash\nclaude mcp add mineru-mcp -e MINERU_API_KEY=your-api-key -- cmd /c npx -y mineru-mcp\ncodex mcp add mineru --env MINERU_API_KEY=your-api-key -- cmd /c npx -y mineru-mcp\n```\n\n### ChatGPT\n\nChatGPT 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.\n\n## Configuration\n\n| Environment Variable | Default | Description |\n|---------------------|---------|-------------|\n| `MINERU_API_KEY` | (required) | Your MinerU API Bearer token |\n| `MINERU_BASE_URL` | `https://mineru.net/api/v4` | API base URL |\n| `MINERU_DEFAULT_MODEL` | `pipeline` | Default model: `pipeline` or `vlm` |\n\nGet your API key at [mineru.net](https://mineru.net)\n\n## Usage\n\n### Parse a single URL\n\n```typescript\nmineru_parse({\n  url: \"https://example.com/document.pdf\",\n  model: \"vlm\",        // optional: \"pipeline\" (default) or \"vlm\" (90% accuracy)\n  pages: \"1-10,15\",    // optional: page ranges\n  ocr: true,           // optional: enable OCR (pipeline only)\n  formula: true,       // optional: formula recognition\n  table: true,         // optional: table recognition\n  language: \"en\",      // optional: language code\n  formats: [\"html\"]    // optional: extra export formats\n})\n```\n\n### Check task progress\n\n```typescript\nmineru_status({\n  task_id: \"abc-123\",\n  format: \"concise\"    // optional: \"concise\" (default) or \"detailed\"\n})\n```\n\n**Concise output**: `done | abc-123 | https://cdn-mineru.../result.zip`\n\n### Batch parse URLs\n\n```typescript\nmineru_batch({\n  urls: [\"https://example.com/doc1.pdf\", \"https://example.com/doc2.pdf\"],\n  model: \"vlm\"\n})\n```\n\n### Check batch progress\n\n```typescript\nmineru_batch_status({\n  batch_id: \"batch-123\",\n  limit: 10,           // optional: max results (default: 10)\n  offset: 0,           // optional: skip first N results\n  format: \"concise\"    // optional: \"concise\" or \"detailed\"\n})\n```\n\n### Upload local files\n\n```typescript\nmineru_upload_batch({\n  directory: \"/path/to/pdfs\",  // scan directory for supported files\n  // OR\n  files: [\"/path/to/doc1.pdf\", \"/path/to/doc2.pdf\"],  // explicit file list\n  model: \"vlm\",        // optional\n  formula: true,       // optional\n  table: true,         // optional\n  language: \"en\",      // optional\n  formats: [\"html\"]    // optional\n})\n```\n\nReturns `batch_id` for tracking. Each file's original name is preserved via `data_id` (spaces become underscores).\n\n### Download results as markdown\n\n```typescript\nmineru_download_results({\n  batch_id: \"batch-123\",       // from mineru_upload_batch or mineru_batch\n  output_dir: \"/path/to/output\",\n  overwrite: false             // optional: overwrite existing files\n})\n```\n\nOutput filenames are derived from `data_id` (e.g., `my_paper_title.md`). Spaces in original filenames become underscores.\n\n### Typical local file workflow\n\n```\nmineru_upload_batch → mineru_batch_status (poll) → mineru_download_results\n```\n\n## Supported Formats\n\n- PDF, DOC, DOCX, PPT, PPTX\n- PNG, JPG, JPEG\n\n## Limits\n\n- Single file: 200MB max, 600 pages max\n- Daily quota: 2000 pages at high priority\n- Batch: max 200 files per request\n\n## License\n\nMIT\n\n## Links\n\n- [MinerU](https://mineru.net) — Document parsing service\n- [MinerU GitHub](https://github.com/opendatalab/MinerU) — Open source version\n- [MCP Specification](https://modelcontextprotocol.io) — Model Context Protocol\n",
  "bytes": 7956,
  "sha": "b196aa568fa8069d8e2060145843395d313fbd5f53f76f9507fe4dc7ec92bfe0",
  "repo_slug": "linxule/mineru-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_linxule_mineru_c3d81938/readme"
}