Skip to main content
Glama
deenesjakoruzh
opendatalab

MinerU Open MCP (Official)

by opendatalab
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

MinerU Open MCP

MinerU-Ecosystem MCP server

Un servidor MCP oficial de MinerU que expone el análisis de documentos de MinerU como herramientas MCP. Conecta cualquier cliente de IA compatible con MCP para convertir archivos PDF, Word, PowerPoint e imágenes a Markdown.

No se requiere clave API: el modo Flash funciona de inmediato, es gratuito y sin registro, aunque tiene límites más bajos. Configura MINERU_API_TOKEN para desbloquear límites más altos y formatos de salida adicionales.

Notas para clientes MCP con sandbox: en algunos clientes MCP, los archivos arrastrados al cuadro de entrada se ejecutan en un entorno aislado (sandbox) en un directorio temporal. Si necesitas cargar y analizar archivos locales, proporciona las rutas completas de los archivos de destino en tu prompt, en caso de que el servidor no pueda encontrar los archivos.

⚡ La forma más rápida de ejecutarlo: uvx (no requiere instalación)

mineru-open-mcp está en PyPI. Con uv instalado, puedes ejecutarlo directamente, sin pasos de instalación adicionales.

Configura tu cliente MCP

stdio: Claude Desktop, Cursor, Windsurf

El cliente MCP inicia mineru-open-mcp como un subproceso automáticamente.

Usando uvx (recomendado: siempre ejecuta la última versión):

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

¿No tienes clave API? El servidor se ejecuta en modo Flash: gratuito, solo markdown, obtén más información en la Documentación del modo Flash

¿mineru-open-mcp no está en el PATH? Usa la ruta completa: "/Users/you/.local/bin/mineru-open-mcp", o usa el enfoque uvx anterior que maneja esto automáticamente.

Related MCP server: MinerU MCP Server

Ejemplos de uso

Ejemplo 1: Analizar un documento PDF local con rangos de páginas específicos

Prompt del usuario: "Analiza de la 3ª a la 5ª página de este PDF a markdown: <tu_ruta_al_archivo>" Qué sucede:

  • MinerU carga y analiza el PDF

  • Devuelve un Markdown limpio con tablas (HTML) y fórmulas (Latex) preservadas

  • Devuelve textos en markdown en el chat si la longitud lo permite, junto con la ruta de salida y la URL del archivo zip si lo prefieres

  • El cliente MCP resume el contenido

Ejemplo 2: Analizar una URL remota que aloja un archivo

Prompt del usuario: "Extrae el contenido de este artículo: https://arxiv.org/pdf/2509.22186" Qué sucede:

  • MinerU analiza el artículo a markdown

  • El cliente MCP formatea y explica las tablas

Ejemplo 3: Analizar archivos PDF locales con rangos de páginas independientes

Prompt del usuario: "Analiza páginas 1-5, páginas 2-9, página 3 a markdown" Qué sucede:

  • MinerU carga y analiza los archivos por separado

  • Devuelve las salidas en el formato solicitado, la URL del zip para descargar, el resumen en markdown y el directorio donde deseas guardar la salida

  • El cliente MCP utiliza el contenido para un análisis posterior

Ejemplo 4: Preferencias personalizadas avanzadas

Prompt del usuario 1: "usa el modelo pipeline para analizar este archivo coreano tu_ruta_aquí" Prompt del usuario 2: "analiza tu_ruta_aquí y guarda el markdown en tu_directorio_de_salida" Qué sucede:

  • El modelo pipeline es otro modelo proporcionado por el servicio MinerU (por cierto, el modelo vlm es la opción predeterminada)

  • Puedes especificar un modelo, un idioma de OCR o incluso un directorio de salida independiente diferente de OUTPUT_DIR estructurando tu prompt

  • Tus solicitudes se parametrizan en la herramienta parse_documents y MinerU se encargará del resto.

streamable-http: clientes MCP basados en web

Inicia el servidor manualmente y luego apunta tu cliente hacia él:

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

Características

  • parse_documents: convierte archivos locales y/o URLs remotas a Markdown; la entrada admite PDF, imágenes (png/jpg/jpeg/jp2/webp/gif/bmp), Doc, Docx, Ppt, PPTx. El modo Flash también admite xlsx.

  • get_ocr_languages: enumera todos los idiomas de OCR admitidos por MinerU

  • Modo Flash: funciona sin clave API (gratuito, solo salida markdown, admite PDF/imágenes/Docx/PPTx/xls/xlsx); para obtener todas las funciones, proporciona MINERU_API_TOKEN, lo que desactivará el modo flash.

  • Comportamiento de salida: los análisis de un solo archivo devuelven Markdown en línea de forma predeterminada; los análisis por lotes guardan los resultados en el disco y devuelven metadatos del archivo. El contenido en línea de gran tamaño también se guarda localmente y se devuelve a través de extract_path.

  • Dos modos de transporte: stdio, streamable-http

Variables de entorno

Variable

Descripción

Predeterminado

MINERU_API_TOKEN

Token de la API de MinerU, solicítalo en MinerU para obtener la capacidad completa. Si no se proporciona, se habilita el modo flash.

—

OUTPUT_DIR

Directorio utilizado cuando los resultados analizados deben guardarse localmente, como en el análisis por lotes o contenido en línea de gran tamaño

~/mineru-downloads

Política de privacidad

mineru-open-mcp se conecta a la API oficial de MinerU (mineru.net) para analizar documentos.

  • Datos enviados: Contenido del documento (archivos o URLs que proporcionas para el análisis)

  • Almacenamiento de datos: Los resultados analizados son almacenados temporalmente en caché por los servidores de MinerU; no se utilizan para entrenamiento

  • Terceros: API de MinerU (mineru.net): consulta la Política de privacidad de OpenDatalab

  • Datos locales: Los resultados analizados se guardarán en el directorio de salida de destino. Los archivos de registro (solo cuando ENABLE_LOG=true) se guardan en MINERU_LOG_DIR;

  • Contacto: OpenDataLab@pjlab.org.cn (o abre un issue en 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.

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