Skip to main content
Glama
deenesjakoruzh
opendatalab

MinerU Open MCP (Official)

by opendatalab
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

MinerU Open MCP

MinerU-Ecosystem MCP server

一个官方的 Mineru MCP 服务器，将 MinerU 的文档解析功能作为 MCP 工具提供。连接任何兼容 MCP 的 AI 客户端，即可将 PDF、Word 文档、PowerPoint 文件和图像转换为 Markdown。

无需 API 密钥 — Flash 模式开箱即用，免费且无需注册，但有较低的使用限制。设置 MINERU_API_TOKEN 可解锁更高的限制和额外的输出格式。

关于带沙盒的 MCP 客户端的说明 - 对于某些 MCP 客户端，拖入输入框的文件会被放入临时目录的沙盒中。如果您需要上传并解析本地文件，请在提示词中提供目标文件的完整路径，以防服务器无法找到文件。

⚡ 最快捷的运行方式 — uvx (无需安装)

mineru-open-mcp 已发布在 PyPI 上。安装 uv 后，您可以直接运行它，无需单独的安装步骤。

配置您的 MCP 客户端

stdio — Claude Desktop, Cursor, Windsurf

MCP 客户端会自动将 mineru-open-mcp 作为子进程启动。

使用 uvx (推荐 — 始终运行最新版本):

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

没有 API 密钥？ 服务器以 Flash 模式运行 — 免费，仅限 Markdown 输出，更多信息请访问 Flash 模式文档

mineru-open-mcp 不在 PATH 中？ 请使用完整路径："/Users/you/.local/bin/mineru-open-mcp"，或者使用上述 uvx 方法，它会自动处理此问题。

Related MCP server: MinerU MCP Server

使用示例

示例 1：解析带有目标页码范围的本地 PDF 文档

用户提示词： "将此 PDF 的第 3-5 页解析为 markdown：<your_path_to_file>" 执行过程：

  • MinerU 上传并解析 PDF

  • 返回保留了表格 (HTML) 和公式 (Latex) 的整洁 Markdown

  • 如果长度允许，在聊天中返回 markdown 文本以及输出路径，如果您需要，还会提供 zip 下载链接

  • MCP 客户端总结内容

示例 2：解析托管文件的远程 URL

用户提示词： "提取此论文的内容：https://arxiv.org/pdf/2509.22186" 执行过程：

  • MinerU 将论文解析为 markdown

  • MCP 客户端格式化并解释表格

示例 3：解析具有独立页码范围的本地 PDF 文件

用户提示词： "将 第 1-5 页， 第 2-9 页， 第 3 页解析为 markdown" 执行过程：

  • MinerU 分别上传并解析文件

  • 返回目标格式输出、供您下载的 zip 链接、markdown 摘要以及您希望保存输出的目录

  • MCP 客户端使用这些内容进行进一步分析

示例 4：高级自定义偏好设置

用户提示词 1： "使用 pipeline 模型解析此韩语文件 your_path_here" 用户提示词 2： "解析 your_path_here 并将 markdown 保存到 your_output_dir" 执行过程：

  • Pipeline 模型是 MinerU 服务提供的另一种模型（顺便提一下，vlm 模型是默认选择）

  • 您可以通过构建提示词来指定模型、OCR 语言，甚至指定一个不同于 OUTPUT_DIR 的独立输出目录

  • 您的请求会被参数化为 parse_documents 工具，MinerU 将处理其余部分。

streamable-http — 基于 Web 的 MCP 客户端

手动启动服务器，然后将您的客户端指向它：

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

功能

  • parse_documents — 将本地文件和/或远程 URL 转换为 Markdown；输入支持 PDF、图像（png/jpg/jpeg/jp2/webp/gif/bmp）、Doc、Docx、Ppt、PPTx。Flash 模式还支持 xlsx。

  • get_ocr_languages — 列出 MinerU 支持的所有 OCR 语言

  • Flash 模式 — 无需 API 密钥即可工作（免费，仅限 markdown 输出，支持 PDF/图像/Docx/PPTx/xls/xlsx）；如需完整功能，请提供 MINERU_API_TOKEN，这将禁用 flash 模式。

  • 输出行为 — 单文件解析默认返回内联 Markdown；批量解析将结果保存到磁盘并返回文件元数据。过大的内联内容也会保存在本地并通过 extract_path 返回。

  • 两种传输模式 — stdio, streamable-http

环境变量

变量

描述

默认值

MINERU_API_TOKEN

MinerU API 令牌，在 MinerU 申请以获取完整功能。如果不提供，则启用 flash 模式。

—

OUTPUT_DIR

当解析结果需要保存在本地时使用的目录，例如批量解析或过大的内联内容

~/mineru-downloads

隐私政策

mineru-open-mcp 连接到官方 MinerU API (mineru.net) 以解析文档。

  • 发送的数据：文档内容（您提供用于解析的文件或 URL）

  • 数据存储：解析结果由 MinerU 服务器临时缓存；不用于训练

  • 第三方：MinerU API (mineru.net) — 请参阅 OpenDatalab 隐私政策

  • 本地数据：解析结果将保存到目标输出目录。日志文件（仅在 ENABLE_LOG=true 时）保存到 MINERU_LOG_DIR；

  • 联系方式：OpenDataLab@pjlab.org.cn (或在 MinerU-Ecosystem 提交 issue)

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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv1.0.18
    • Addedget_ocr_languages
    • Addedparse_documents
  2. 2 tool updatesv1.0.16
    • Removedget_ocr_languages
    • Removedparse_documents
  3. 2 tool updatesv1.0.15
    • First observedget_ocr_languages
    • First observedparse_documents
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.6/5.0

Scored across 2 tools

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
ResponsivenessWithin a week

Resources

Related MCP Connectors

Related MCP Servers