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 package provides eight tools. Version 1.2.0 adds mineru_parse_long and mineru_merge_slices for long documents.

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

Download completed batch results into named folders with {name}.md, an optional {name}_content.json, and available images/. This requires unzip on the machine. The reviewed source recognizes UUID-prefixed content-list filenames that older downloads could miss.

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; unzip must be installed on the machine. The tool reports pending or failed slices without merging; unexpected states or completed slices without a ZIP produce an error. The MCP call does not wait. Once ready, it orders slices by their encoded ranges, adds slice comments to Markdown, prefixes image names/references to avoid collisions, and saves one document folder. Paged content lists are concatenated in document order; numeric page_idx fields are rebased to the original document's zero-based page numbers.

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.

Install the package with Bun to make both executables available. Version 1.1.6 does not include the CLI; update an older installation first.

bun add --global mineru-mcp@1.2.0
# 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. Commands drop mineru_ and replace underscores with hyphens: parse, status, batch, batch-status, upload-batch, download-results, parse-long, and merge-slices. 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 repeats recognized status/merge/download progress every 10 seconds, with a 30-minute polling budget; it does not turn submission commands into end-to-end jobs. Errors go to stderr with exit 1; final tool text goes to stdout and can include failed tasks, partial downloads, or merge notes even with exit 0.

At the reviewed revision, wait detection is text-based: detailed batch-status output is not polled, concise status can omit failed entries outside its page, and download-results can return immediately when nothing has finished. Inspect batch state explicitly rather than treating --wait or exit 0 as a completeness check. merge-slices --wait polls while recognized pending slices remain; failures alone are final reports, not automatic retries.

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 via npx, Smithery, or a local clone.

The MCP entry point remains mineru-mcp; mineru-cloud is the separate shell entry point in the same package. Version 1.1.6 fixed the adapter-resolution problem in fresh 1.1.5 installs. Version 1.2.0 retains the declared Node.js 18-or-newer runtime requirement.

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, 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
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

{
  "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"
      }
    }
  }
}

npx -y @smithery/cli mcp add linxule/mineru-mcp --client claude

Configuration options

MinerU MCP supports 11+ client configurations, including Windsurf, Cline, Cherry Studio, and Witsy; the full setup guide on GitHub 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 maintainer's 16 September source records a 200-page cap per parsing request and 1,000 high-priority pages/day, with excess pages deprioritized rather than rejected. It retains a 200MB file limit and a 200-entry batch limit. Use at most 200 pages per slice for the documented long-document workflow.

There is a documentation discrepancy: the vendor's English API guide still states 600 pages and 2,000 priority pages/day at this review. The tighter values above are source-owner-reported observations, not a new live parse test by Research Memex. Check current service/account limits before a large job; neither source establishes a throughput guarantee. Separate API rate and daily upload limits also apply.

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
• npm: mineru-mcp
• Smithery: Install for any AI client
• MinerU Platform: mineru.net
• MinerU Open Source: opendatalab/MinerU
• Related: OCR Guide | SLR Workflow