Mineru Open Mcp

MinerU Open MCP

An Official Mineru MCP server that exposes MinerU's document parsing as MCP tools. Connect any MCP-compatible AI client to convert PDFs, Word docs, PowerPoint files, and images into Markdown.

No API key required — Flash mode works out of the box, free with no sign-up but lower limits are applied. Set MINERU_API_TOKEN to unlock higher limits and extra output formats.

Notes for MCP clients with sandbox - For some MCP clients, your files dragged into the input box are sandboxed into a temporary directory. If you need to upload and parse local files, please provide full paths of the target files in your prompt, in case files cannot be found by the server.

---

⚡ Quickest Way to Run — uvx (no install needed)

mineru-open-mcp is on PyPI. With uv installed, you can run it directly — no separate install step.

Configure your MCP client

stdio — Claude Desktop, Cursor, Windsurf

The MCP client launches mineru-open-mcp as a subprocess automatically.

Using uvx (recommended — always runs the latest version):

{
  "mcpServers": {
    "mineru": {
      "command": "uvx",
      "args": ["mineru-open-mcp"],
      "env": {
        "MINERU_API_TOKEN": "your_key_here"
      }
    }
  }
}

No API key? The server runs in Flash mode — free, markdown-only, learn more at Flash Mode Docs

mineru-open-mcp not on PATH? Use the full path: "/Users/you/.local/bin/mineru-open-mcp", or use the uvx approach above which handles this automatically.

Usage Examples

Example 1: Parse a local PDF document with target page ranges

User prompt: "Parse the 3rd-5th pages of this PDF into markdown: <your_path_to_file>" What happens:

• MinerU uploads and parses the PDF
• Returns clean Markdown with tables (HTML) and formulas (Latex) preserved
• Returns markdown texts in the chat if length permitted along with the output path, and the zip url if you prefer
• MCP client summarizes the content

Example 2: Parse a remote url hosting a file

User prompt: "Extract contents from this paper: https://arxiv.org/pdf/2509.22186" What happens:

• MinerU parses the paper into markdown
• MCP client formats and explains the tables

Example 3: Parse local PDF files with independent page ranges

User prompt: "Parse <file1> page 1-5, <file2> page 2-9, <file3> page 3 into markdown" What happens:

• MinerU uploads and parses the files separatedly
• Returns target format ouputs, the zip url for you to download, markdown abstract, the directory you want to save the output to
• MCP client uses the content for further analysis

Example 4: Advanced custom preferences

User prompt1: "use pipeline model to parse this Korean file your_path_here" User prompt2: "parse your_path_here and save the markdown to your_output_dir" What happends:

• Pipeline model is another model provided by MinerU service (BTW, vlm model is the default choice)
• You are allowed to specify a model, an ocr language, or even an independent output dir different from OUTPUT_DIR by structuring your prompt
• Your requests are parameterized into parse_documents tool and MinerU will handle the rest.

streamable-http — web-based MCP clients

Start the server manually, then point your client at it:

MINERU_API_TOKEN=your_key mineru-open-mcp --transport streamable-http --port 8001

{
  "mcpServers": {
    "mineru": {
      "type": "streamableHttp",
      "url": "http://127.0.0.1:8001/mcp"
    }
  }
}

Features

• parse_documents ? convert local files and/or remote URLs to Markdown; Input supports PDF, images（png/jpg/jpeg/jp2/webp/gif/bmp, Doc, Docx, Ppt, PPTx. Flash Mode also supports xlsx.
• get_ocr_languages — list all OCR languages supported by MinerU
• Flash mode — works without an API key (free, markdown output only, supports PDF/images/Docx/PPTx/xls/xlsx); For full features, please provide MINERU_API_TOKEN, which will disable flash mode.
• Output behavior ? single-file parses return inline Markdown by default; batch parses save results to disk and return file metadata. Oversized inline content is also saved locally and returned via extract_path.
• Two transport modes ? stdio, streamable-http

---

Environment Variables

Variable	Description	Default
MINERU_API_TOKEN	MinerU API token, apply on MinerU for full capability. If not provided, flash mode is enabled.	—
OUTPUT_DIR	Directory used when parsed results need to be saved locally, such as batch parsing or oversized inline content	~/mineru-downloads

Privacy Policy

mineru-open-mcp connects to the official MinerU API (mineru.net) to parse documents.

• Data sent: Document content (files or URLs you provide for parsing)
• Data storage: Parsed results are temporarily cached by MinerU servers; not used for training
• Third-party: MinerU API (mineru.net) — see OpenDatalab Privacy Policy
• Local data: Parsed results will be saved to target output directory. Log files (only when ENABLE_LOG=true), saved to MINERU_LOG_DIR;
• Contact: [email protected] (or raise an issue at MinerU-Ecosystem )