# MinerU MCP: Document Parsing URL: https://research-memex.org/docs/toolkit/mineru-mcp Description: MinerU MCP turns difficult documents into agent-readable text while keeping parsing steps inspectable. *Complex documents only become research material when they become readable text.* MinerU MCP integrates [MinerU's](https://mineru.net) document parsing API directly into Claude, so you can parse difficult documents without switching tools. Version: [1.1.4](https://github.com/linxule/mineru-mcp) | Stats: 90%+ accuracy (VLM mode) | 109 languages | Up to 200 documents per batch | 73% token reduction ## Why it matters [#why-it-matters] An MCP server that wraps MinerU's document parsing API for Claude Code research workflows. Instead of switching between tools or running scripts, you can parse documents directly within the conversation. Why use MinerU MCP instead of manual conversion? * integrated workflow: parse documents without leaving Claude * multi-format support: PDF, DOC, DOCX, PPT, PPTX, PNG, JPG, JPEG * batch processing: handle 200 documents simultaneously * local file workflow: upload files from your machine, poll for completion, download results * quality options: choose speed (Pipeline) or accuracy (VLM) * 73% token reduction: shorter tool descriptions for lower context usage ## How it works [#how-it-works] Use for: academic papers, complex layouts, tables, formulas * 90%+ accuracy using Vision Language Models * Slower processing. Worth the wait for important documents. * Higher API cost * Better for SLR corpora where accuracy matters ``` Parse with model='vlm' for maximum accuracy ``` Use for: simple documents, speed priority, exploratory screening * Faster processing * Lower cost * Good for initial screening passes * Default mode for quick tasks ``` Quick parse this document for initial review ``` ## Tools [#tools] MinerU MCP provides six tools covering two workflows: URL-based parsing (tools 1--4) and a local file pipeline (tools 5--6). ### 1. `mineru_parse` [#1-mineru_parse] Process a single document with customizable options. | Parameter | Description | Default | | ---------- | ---------------------------------------- | --------- | | `url` | Document URL (required) | - | | `model` | `pipeline` (fast) or `vlm` (accurate) | pipeline | | `pages` | Page ranges to parse (e.g. `"1-10,15"`) | all pages | | `formats` | Extra export formats beyond markdown | - | | `ocr` | Enable OCR for scanned documents | false | | `formula` | Recognize mathematical/chemical formulas | false | | `table` | Detect and extract tables | true | | `language` | OCR language (109 supported) | `en` | Example prompt: ``` Parse pages 1-25 of this paper with VLM mode for maximum accuracy: https://arxiv.org/pdf/2401.12345.pdf ``` ### 2. `mineru_status` [#2-mineru_status] Check task completion and get download URLs. | Parameter | Description | Default | | --------- | --------------------------------------- | ------- | | `task_id` | Task ID from a parse request (required) | - | | `format` | `concise` or `detailed` response | concise | Example prompt: ``` Check the status of my parsing job and download the markdown when ready ``` ### 3. `mineru_batch` [#3-mineru_batch] Process multiple document URLs simultaneously for SLR corpus preparation. Limits: * Maximum 200 documents per batch * 200MB per file, 600 pages per document * 2000 pages/day at high priority Example prompt: ``` Batch process these 50 papers using VLM mode for my literature review: [list of URLs] ``` ### 4. `mineru_batch_status` [#4-mineru_batch_status] Retrieve paginated results from batch jobs. | Parameter | Description | Default | | ---------- | ---------------------------------------- | ------- | | `batch_id` | Batch ID from a batch request (required) | - | | `limit` | Number of results to return | - | | `offset` | Pagination offset | 0 | | `format` | `concise` or `detailed` response | concise | ### 5. `mineru_upload_batch` [#5-mineru_upload_batch] Upload local files from your machine for batch processing. No need to host files at a URL. | Parameter | Description | Default | | ----------- | ------------------------------------- | -------- | | `directory` | Path to a folder of documents | - | | `files` | Array of specific file paths | - | | `model` | `pipeline` (fast) or `vlm` (accurate) | pipeline | | `formula` | Recognize formulas | false | | `table` | Detect and extract tables | true | | `language` | OCR language | `en` | | `formats` | Extra export formats | - | Provide either `directory` or `files` (not both). ### 6. `mineru_download_results` [#6-mineru_download_results] Download processed results as named markdown files to a local directory. | Parameter | Description | Default | | ------------ | ------------------------------------------- | ------- | | `batch_id` | Batch ID to download results for (required) | - | | `output_dir` | Local directory for output files (required) | - | | `overwrite` | Overwrite existing files | false | Local file workflow: tools 5 and 6 enable a complete local pipeline. Upload files from your machine with `mineru_upload_batch`, poll with `mineru_batch_status`, then save results with `mineru_download_results`. No URLs or manual downloads needed. ## Use cases for research [#use-cases-for-research] ### 1. SLR corpus preparation [#1-slr-corpus-preparation] Converting 50+ papers for systematic review: ``` I have 47 papers from my Scopus search that need to be converted to markdown for analysis. Here are the URLs: [paste URLs] Use VLM mode for accurate table extraction. This is for my systematic literature review on organizational learning. ``` ### 2. Local file processing [#2-local-file-processing] When your papers are already downloaded (e.g., from Zotero): ``` Upload all PDFs in ~/Documents/slr-papers/ using VLM mode, then download the results to ~/Documents/slr-markdown/ ``` ### 3. Batch processing for literature analysis [#3-batch-processing-for-literature-analysis] Screen a large set before detailed analysis: ``` Quick parse these 100 papers using pipeline mode to extract abstracts and main sections. I'll do detailed VLM parsing on the 20 most relevant ones later. ``` ### 4. Multilingual research [#4-multilingual-research] MinerU supports 109 OCR languages: ``` Parse this German-language paper with OCR enabled and language set to 'de'. Extract the methodology section. ``` ## Host support [#host-support] MinerU runs as a standard stdio MCP server, available via `npx`, Smithery, or a local clone. The public package still installs through `npx -y mineru-mcp`. Recent source updates moved contributor tooling and release automation to Bun/OIDC. Users do not need Bun for normal MCP usage. Per-host install commands are in the Install section below. ## Install [#install] Two ways to set MinerU up: * Manually — get a `MINERU_API_KEY` from [mineru.net](https://mineru.net), then register the MCP with your client. See the steps below. * Via [Carrel](/docs/toolkit/carrel) — run `/carrel-setup` and say yes when the interview asks about complex / scanned PDFs. Carrel adds MinerU at project level and prompts for the API key. The manual path works in any MCP client; the Carrel path is Claude Code-only but skips the config steps. ### Installation & setup [#installation--setup] #### Step 1: get API key [#step-1-get-api-key] 1. Visit [mineru.net](https://mineru.net) 2. Create account and generate API key 3. Save securely (you'll need it for configuration) #### Step 2: install MCP [#step-2-install-mcp] ```bash claude mcp add mineru-mcp -e MINERU_API_KEY=your-api-key -- npx -y mineru-mcp ``` Verify with `claude mcp list`. You should see `mineru-mcp` available. ```bash codex mcp add mineru --env MINERU_API_KEY=your-api-key -- npx -y mineru-mcp ``` Antigravity CLI has a plugin/settings surface, but the currently verified `agy` command set does not include a top-level MCP add subcommand. Use Antigravity's documented MCP or plugin configuration path when Google publishes the exact host syntax; do not translate the old Gemini CLI MCP command literally. Add to `~/Library/Application Support/Claude/claude_desktop_config.json`: ```json { "mcpServers": { "mineru": { "command": "npx", "args": ["-y", "mineru-mcp"], "env": { "MINERU_API_KEY": "your-api-key" } } } } ``` Add to your MCP settings JSON (VS Code uses `servers`, Cursor uses `mcpServers`): ```json { "mcpServers": { "mineru": { "command": "npx", "args": ["-y", "mineru-mcp"], "env": { "MINERU_API_KEY": "your-api-key" } } } } ``` ```bash npx -y @smithery/cli mcp add linxule/mineru-mcp --client claude ``` Works with Claude Desktop, Cherry Studio, and other MCP clients. Set your API key in environment variables. ### Configuration options [#configuration-options] MinerU MCP supports 11+ client configurations, including Windsurf, Cline, Cherry Studio, and Witsy; the [full setup guide on GitHub](https://github.com/linxule/mineru-mcp#installation) lists every option. Configure the variables below for whichever client you use. | Variable | Default | Purpose | | ---------------------- | --------------------------- | ---------------------------- | | `MINERU_API_KEY` | Required | Bearer token from mineru.net | | `MINERU_BASE_URL` | `https://mineru.net/api/v4` | API endpoint | | `MINERU_DEFAULT_MODEL` | `pipeline` | Default parsing mode | ## Part of Research Memex [#part-of-research-memex] ### With OCR guide [#with-ocr-guide] MinerU MCP is the recommended approach for PDF conversion in Research Memex workflows. See the [PDF to Markdown Conversion Guide](/docs/implementation/ai-environment-setup/ocr-pdf-conversion-guide) for comparison with other methods. ### With SLR workflow [#with-slr-workflow] Use MinerU for batch PDF processing in your [Systematic Literature Review workflow](/docs/case-studies/systematic-reviews/claude-code-slr-workflow). It works well when Zotero exports need to become agent-readable markdown. ### With Interpretive Orchestration [#with-interpretive-orchestration] MinerU is bundled as an optional MCP in the [Interpretive Orchestration Plugin](/docs/toolkit/interpretive-orchestration-plugin) for qualitative research. It powers document ingestion alongside Markdownify for a complete document processing pipeline. ## MinerU vs Mistral OCR [#mineru-vs-mistral-ocr] | Feature | MinerU MCP | [Mistral OCR](https://docs.mistral.ai/studio-api/document-processing/basic_ocr) (Script) | | ----------- | --------------------------------- | ---------------------------------------------------------------------------------------- | | Integration | MCP (inline in Claude) | Python script | | Use case | Claude workflows, real-time | Bulk offline processing | | Formats | PDF, DOC, DOCX, PPT, PPTX, images | PDF only | | Batch limit | 200 docs | Unlimited | | VLM mode | Yes (90%+) | No | | Local files | Yes (upload\_batch) | Yes | | Languages | 109 | Variable | | Setup | API key + MCP | API key + Python | | Cost | Per-page API | Per-page API | Recommendation: Use MinerU MCP for integrated Claude workflows and multi-format documents. Use Mistral script for very large offline batch jobs. ## Limitations & considerations [#limitations--considerations] * API key: get one from [mineru.net](https://mineru.net) * File size: 200MB max per file * Page limit: 600 pages per document * Daily quota: 2000 pages at high priority * VLM mode: More accurate but slower and costlier ## Resources [#resources] * GitHub: [linxule/mineru-mcp](https://github.com/linxule/mineru-mcp) * npm: [mineru-mcp](https://www.npmjs.com/package/mineru-mcp) * Smithery: [Install for any AI client](https://smithery.ai/server/@linxule/mineru-mcp) * MinerU Platform: [mineru.net](https://mineru.net) * MinerU Open Source: [opendatalab/MinerU](https://github.com/opendatalab/MinerU) * Related: [OCR Guide](/docs/implementation/ai-environment-setup/ocr-pdf-conversion-guide) | [SLR Workflow](/docs/case-studies/systematic-reviews/claude-code-slr-workflow)