Skip to main content
Glama
deenesjakoruzh
opendatalab

MinerU Open MCP (Official)

by opendatalab
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

MinerU Open MCP

MinerU-Ecosystem MCP server

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.

Related MCP server: MinerU MCP Server

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: OpenDataLab@pjlab.org.cn (or raise an issue at MinerU-Ecosystem )

Available Tools

2 tools
get_ocr_languagesList OCR language codesA
Read-only

Return supported MinerU OCR and script language codes (e.g. ch, en, japan, latin). Read-only; no uploads. Use before setting the language argument on parse_documents for scanned or multilingual documents. Do not use for file conversion; call parse_documents instead.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds 'Read-only; no uploads,' which reinforces and complements the annotations without contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three succinct sentences with no wasted words. Purpose, behavioral note, and usage guidance are each in separate, front-loaded sentences.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter tool with an output schema, the description adequately covers its purpose, when to use it, and behavioral constraints. No missing information.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has zero parameters, so schema coverage is 100%. No parameter information needed; baseline is 4. Description correctly omits param details.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns supported OCR language codes, specifying verb 'Return' and resource 'MinerU OCR and script language codes'. It distinguishes from the sibling tool parse_documents.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use ('before setting the language argument on parse_documents for scanned or multilingual documents') and when not to ('Do not use for file conversion'), with a direct alternative (parse_documents).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

parse_documentsParse documents to MarkdownA

Convert PDF, Office (DOCX, PPTX), spreadsheets (XLSX in Flash mode), images, and http(s) URLs to Markdown using the MinerU cloud API (content is uploaded to mineru.net; do not use for data that must stay on-device). Does not modify source files; may write Markdown under output_dir when saving results. Auth: without MINERU_API_TOKEN, Flash mode applies (Markdown-only, about 20 pages and 10 MB per file; service rate limits). With MINERU_API_TOKEN, higher limits and optional formats per plan. Use for extraction and conversion. Use get_ocr_languages only to list OCR language codes, not to parse files. Not for fully offline parsing. Parameters: file_sources is paths/URLs or objects with source and pages for PDF ranges; language is an OCR code (default ch); enable_ocr defaults to auto (null); set model to html only if every source is a web page URL.

ParametersJSON Schema
NameRequiredDescriptionDefault
file_sourcesYesFiles to parse. Each entry is either: - a plain string: a local file path or URL - a dict {"source": "...", "pages": "N-M"}: with an optional page range Page range: "N" (single page) or "N-M" (for example "1-10"). PDF only. Duplicate sources are allowed, for example the same PDF with different ranges. Examples: ["report.pdf"] [{"source": "report.pdf", "pages": "1-5"}] [{"source": "a.pdf", "pages": "1-3"}, {"source": "a.pdf", "pages": "10-15"}] ["https://example.com/doc.pdf", "local.docx"]
enable_ocrNoOCR mode: null (default) - auto-detect: the server decides whether OCR is needed. true - force OCR on when the user mentions poor scan quality. false - disable OCR. Omit this parameter unless the user explicitly mentions scan quality issues.
languageNoOCR language code. Omit if unknown; the server defaults to "ch" (Chinese + English). Infer from the document filename when possible, for example "manual_en.pdf" -> "en". Common codes: "ch", "en", "japan", "korean", "latin", "arabic", "cyrillic", "devanagari". Full list: call get_ocr_languages.
modelNoParsing model. Set to "html" only when all file_sources are web page URLs. Otherwise omit it and let MinerU auto-select the appropriate model. Ignored in Flash mode.
output_dirNoDirectory used when parsed results need to be saved locally, such as batch parsing or oversized inline content. Defaults to the server-configured directory.

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses data uploaded to mineru.net (beyond annotations), non-destructive nature, and potential file writes. Annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true) are consistent with description; no contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Concise multi-sentence description with logical flow: function, caveats, usage guidance, parameter tips. No redundancy; each sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers complex tool with 5 params, auth modes, output behavior, and offline limitation. Output schema exists, so return value details are not needed. Complete for agent decision-making.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline 3. Description adds value by summarizing key usage hints for parameters (e.g., file_sources examples, enable_ocr auto-detection, model='html' condition). Minor improvement over schema alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Convert' and the resource 'PDF, Office, spreadsheets, images, and URLs to Markdown'. It distinguishes from sibling tool get_ocr_languages by noting its exclusive use for listing OCR codes, not parsing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use ('Use for extraction and conversion'), when not ('Not for fully offline parsing'), and mentions alternative (get_ocr_languages). Also covers auth-dependent behaviors and rate limits.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.6/5.0
Disambiguation5/5

The two tools have entirely distinct purposes: one lists OCR language codes, the other performs document parsing. There is no overlap or ambiguity.

Naming Consistency5/5

Both tool names follow a clear verb_noun pattern (get_ocr_languages, parse_documents), ensuring predictability and consistency.

Tool Count3/5

With only two tools, the server is at the lower end of reasonable scope. While it covers core functionality, additional tools for status checking or format listing would improve completeness.

Completeness3/5

The tool set covers the primary use case (document conversion) and a helper for language codes, but lacks operations like checking conversion status or listing all supported formats, creating minor gaps.

Maintenance

ActivityInactive
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/opendatalab/MinerU-Ecosystem'

If you have feedback or need assistance with the MCP directory API, please join our Discord server