MinerU MCP: Document Parsing

The MCP server lets an agent submit documents, inspect progress, and save results alongside a research corpus. The CLI invokes those same tools in-process, rather than maintaining a second parser.

Why use MinerU MCP instead of manual conversion?

• integrated workflow: parse documents from an MCP client or the CLI
• multi-format support: PDF, DOC, DOCX, PPT, PPTX, PNG, JPG, JPEG
• batch processing: submit up to 200 documents per request, then inspect their individual states
• local-file input: upload files from your machine, poll for completion, download results
• parsing options: compare Pipeline and VLM on representative pages before processing a corpus

Choose pipeline or vlm. The wrapper uses MINERU_DEFAULT_MODEL when model is omitted, falling back to pipeline. VLM is worth testing on complex layouts, tables, and formulas; neither mode removes the need to inspect the extracted text against the original. No corpus-independent accuracy or cost advantage is asserted here.

The published 2.0.0 package provides the eight compatibility tools below and six durable-operation tools. The latter keep a local journal so interrupted work can be inspected and resumed without blindly submitting another parse.

1. mineru_parse

Process a single document with customizable options.

formats accepts docx, html, or latex in an array. The wrapper forwards optional recognition/language settings only when supplied; it does not set the former documented formula=false or language=en defaults. Set them explicitly when the workflow depends on them.

Example prompt:

Parse pages 1-25 of this paper with VLM mode, then inspect the tables:
https://arxiv.org/pdf/2401.12345.pdf

2. mineru_status

Check task completion and get download URLs.

Example prompt:

Check the status of my parsing job and download the markdown when ready

3. mineru_batch

Process multiple document URLs simultaneously for SLR corpus preparation.

urls accepts an array or a single URL string. It supports the same model, OCR, formula, table, language, and extra-format options as mineru_parse, but not its pages parameter. For page ranges use single-document parsing or the long-document tool. See limits and considerations before a large batch.

Example prompt:

Batch process these 50 papers using VLM mode for my literature review:
[list of URLs]

4. mineru_batch_status

Retrieve paginated results from batch jobs.

5. mineru_upload_batch

Upload local files from your machine for batch processing. No need to host files at a URL.

Choose either directory or files; if both are passed, files takes precedence. Directory scanning is non-recursive. This tool has no ocr or pages option. Uploading sends the file bytes to the service; prefer an already-public URL when appropriate, not publishing a private file to obtain one.

6. mineru_download_results

Version 2.0.0 retains the downloaded archive and its member inventory. It makes compatibility copies such as Markdown and images when selection is unambiguous. It does not need a shell unzip executable. Inspect the inventory and per-file result before assuming that every requested document produced usable text.

7. mineru_parse_long

Submit exactly one url or absolute local file, plus total_pages. Page-count detection is attempted only for local files on macOS through Spotlight; supply the count if metadata is missing. slice_size is a positive integer capped at 200 and defaults to 200. The tool submits one batch of page-range requests, rejecting plans with more than 200 slices. It does not physically split the PDF or bypass the file-size limit.

Optional name, model, ocr, formula, table, and language control the job; formats is not supported here. Each slice receives a range-bearing data_id, such as book__p00001-00200, so it can be ordered during merging. For a local file, the entire file is uploaded once per slice, not once per document. Inspect any upload-problem report before polling.

8. mineru_merge_slices

Pass the long-document batch_id and output_dir. Inspect pending, failed and completed slices before accepting the merge. The MCP call does not wait; the CLI can poll a result marked pollable. Version 2.0.0 retains archive-referenced slice receipts rather than the flattened, rebased content list returned by 1.2.0. Check those receipts against the original page ranges instead of assuming the old structured-output shape.

An existing output folder is refused unless overwrite=true; that option replaces the folder. Missing Markdown or unreadable content lists can yield an incomplete result with notes. Check the merged/expected slice counts, notes, images, and page coverage against the original. A separately resubmitted range does not automatically repair the original batch.

Published durable operations

Version 2.0.0 includes these six MCP/CLI surfaces:

• mineru_capabilities / capabilities — inspect known provider capabilities;
• mineru_submit / submit — journal a durable upload with duplicate protection;
• mineru_operation_status / operation-status — read a recorded operation;
• mineru_resume / resume — continue a safe checkpoint;
• mineru_cancel / cancel — stop local processing (not remote provider work); and
• mineru_bundle / bundle — validate or return a retained offline bundle.

The journal lives under ~/.local/share/mineru-cloud by default, retains source and output evidence for recovery, and fails closed rather than automatically resubmitting an uncertain remote job. A journal records evidence, not permission to send sensitive documents to the cloud.

The published submit --pages accepts positive page numbers and ascending inclusive ranges, such as 1-2,5. It rejects invalid or oversized selectors before reading the source or contacting the provider. New bundles record the requested ranges with coverage still unknown. Replaying an older operation preserves its recorded bundle.

The page-mapping adapter can validate a contiguous range starting at original page 1 when the exact source bytes, page count, and request evidence agree. It cannot yet map suffixes, disjoint ranges, or physical slices to original pages. A page map alone does not establish complete extraction.

Install the published package with Bun or npm to make both executables available:

bun add --global mineru-mcp
# or: npm install --global mineru-mcp
# No API key or document request needed for these two commands.
mineru-cloud --help
mineru-cloud list

The CLI calls the MCP server in-process. Compatibility commands drop mineru_ and replace underscores with hyphens: parse, status, batch, batch-status, upload-batch, download-results, parse-long, and merge-slices. The durable commands listed above use the same naming rule. Options follow the same rule (total_pages becomes --total-pages). It accepts --name 2026 or --name=2026 as a string, converts numeric/boolean fields according to their schemas, and parses JSON for array/object fields. Use explicit booleans such as --table false and shell-quoted arrays such as --formats '["html"]'. Consult list; not every option belongs to every tool.

After separately authorizing cloud processing and configuring MINERU_API_KEY, a long-document workflow is:

mineru-cloud parse-long --url https://example.org/book.pdf --total-pages 520 --name book
# Replace the example URL and returned batch ID with your own.
mineru-cloud merge-slices --batch-id BATCH_ID --output-dir ./books --wait

--wait polls only when the structured result says pollable: true. It checks every 10 seconds, with a 30-minute default budget; --wait-timeout-seconds can set a bounded alternative. Durable submit --wait continues the recorded operation through resume; it does not submit a new parse on each poll.

For durable commands, --json returns the structured result: exit 0 means success, 1 means partial/error, and 2 means invalid arguments. Compatibility commands retain exit 1 for errors and exit 2 for partial or unknown outcomes. The offline bundle command has its own receipt shape. Inspect state, errors, receipts and page coverage as well as the exit status; none alone establishes a complete extraction.

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 and flag tables that need checking. This is for my
systematic literature review on organizational learning.

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

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

Set the document language explicitly and check the result:

Parse this German-language paper with OCR enabled and
language set to 'de'. Extract the methodology section.

MinerU runs as a standard stdio MCP server, available from the published package or a local clone.

The MCP entry point remains mineru-mcp; mineru-cloud is the separate shell entry point in the same package. Both require Node.js 20 or newer.

Per-host install commands are in the Install section below.

Two ways to set MinerU up:

• Manually — get a MINERU_API_KEY from mineru.net (opens in a new tab), then register the MCP with your client. See the steps below.
• Via 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

Step 1: get API key

1. Visit mineru.net (opens in a new tab)
2. Create account and generate API key
3. Save securely (you'll need it for configuration)

Step 2: install MCP

claude mcp add mineru-mcp -e MINERU_API_KEY=your-api-key -- npx -y mineru-mcp

codex mcp add mineru --env MINERU_API_KEY=your-api-key -- npx -y mineru-mcp

agy mcp add mineru-mcp -- npx -y mineru-mcp

{
  "mcpServers": {
    "mineru": {
      "command": "npx",
      "args": ["-y", "mineru-mcp"],
      "env": {
        "MINERU_API_KEY": "your-api-key"
      }
    }
  }
}

{
  "mcpServers": {
    "mineru": {
      "command": "npx",
      "args": ["-y", "mineru-mcp"],
      "env": {
        "MINERU_API_KEY": "your-api-key"
      }
    }
  }
}

Configuration options

MinerU MCP supports 11+ client configurations, including Windsurf, Cline, Cherry Studio, and Witsy; the full setup guide on GitHub (opens in a new tab) lists every option. Configure the variables below for whichever client you use.

With OCR guide

MinerU MCP integrates PDF conversion into Research Memex workflows when cloud processing is approved. See the PDF to Markdown Conversion Guide for comparison with other methods.

With SLR workflow

Use MinerU for batch PDF processing in your Systematic Literature Review workflow. It works well when Zotero exports need to become agent-readable markdown.

With Interpretive Orchestration

MinerU is an optional MCP for the Interpretive Orchestration Plugin, converting source documents before qualitative analysis.

Both routes require network access and permission to send the documents to the chosen service. A shell command or locally running script is not an offline OCR engine. The OCR guide separates hosted and local choices.

The local long-document workflow enforces a 200-page slice maximum. This is a client safety check, not the vendor's service-wide page quota. Use at most 200 pages per slice with this workflow.

The vendor's Precision Extract API guide (opens in a new tab), reviewed October 19, 2026, documents 600 pages and 200MB per file, at most 200 entries per batch, and 2,000 high-priority pages per account per day. Further pages receive lower priority. These are published limits, not account enforcement tested by Research Memex. The separate lightweight Agent API has different limits. Check the current service/account limits and API rate and daily upload limits (opens in a new tab) before a large job; none is a throughput guarantee.

Keep credentials out of shared prompts and shell history. Authentication errors need a credential check by the owner, not an automatic upload retry. pages selects what to parse, not what bytes a local upload discloses.

• GitHub: linxule/mineru-mcp (opens in a new tab)
• npm: mineru-mcp (opens in a new tab)
• MinerU Platform: mineru.net (opens in a new tab)
• MinerU Open Source: opendatalab/MinerU (opens in a new tab)
• Related: OCR Guide | SLR Workflow