MinerU MCP

[MinerU MCP — Extracción y parseo de PDFs para agentes IA vía Model Context Protocol]

English · Español

MinerU MCP — Extracción y parseo de PDFs para agentes IA vía Model Context Protocol (MCP)

Transforma cualquier documento PDF en Markdown estructurado, tablas y código LaTeX para tus agentes IA. Servidor MCP open source que expone las capacidades de extracción de MinerU (PDF-Extract-Kit / MinerU2.5-VLM) a Claude Code, Cursor, Windsurf, Hermes Gateway y cualquier cliente compatible con Model Context Protocol. FastMCP HTTP/SSE + soporte para path local o Base64, cero dependencias en clientes, 100% en tu hardware.

[License: MIT] [MCP] [Python] [CI] [FastMCP] [PRs Welcome]

Tags: mcp-server · mineru · pdf-parser · ocr · latex · ai-agents · fastmcp · claude-code · cursor · hermes-gateway · local-first · self-hosted

[El agente manda dos páginas de un paper real por MCP y recibe Markdown con una ecuación en LaTeX y una tabla]

_{El agente manda un PDF por MCP y recibe Markdown con ecuaciones en LaTeX y tablas — MinerU corre en tu server, el cliente no instala PyTorch. Grabado con scripts/demo_parse.py contra un mineru-api real.}

💡 Por qué existe

Extraer texto estructurado, tablas complejas y fórmulas matemáticas de archivos PDF suele requerir entornos Python pesados con PyTorch, OCR y modelos de visión en cada máquina cliente. MinerU MCP resuelve esto actuando como un adaptador middleware HTTP/SSE desacoplado:

• 🚀 Cero Instalación Local: Cualquier cliente MCP procesa documentos vía HTTP/SSE en puerto 8202 pasando un file_path local o enviando el PDF codificado en file_base64.
• 📊 Markdown Estructurado y LaTeX: Convierte encabezados, listas, tablas complejas y ecuaciones matemáticas en código LaTeX estándar listo para RAG.
• 🧠 La GPU se comparte, no se pelea: pipeline (default) pide ~1.5 GB de VRAM; hybrid-engine y vlm-engine ~4 GB y dan más precisión. Si el host tiene el GPU Broker, cada parseo le pide la VRAM antes y la devuelve al terminar, así que convive con un LLM local en la misma tarjeta.

⚡ Quickstart

mineru-mcp es solo la capa MCP: necesitas un mineru-api corriendo (mineru==3.4.4). Cómo montarlo en el host: docs/SERVER_SETUP.md.

Hay dos formas de correrlo. Elige una:

Requisito: uv ≥ 0.13.4 (o pip ≥ 26.2.2); las versiones anteriores aún confían en la CA emSign comprometida (GHSA-6q48-6c7w-9gw2). uv pip install -e . lo comprueba solo ([tool.uv] required-version en pyproject.toml); uvx --from git+… no, porque corre fuera del proyecto: revisa uv --version.

Opción A — HTTP (server compartido)

git clone https://github.com/GermaniU/mineru-mcp.gitcd mineru-mcpuv venv && source .venv/bin/activateuv pip install -e .MINERU_URL=http://127.0.0.1:8000 mineru-mcp

Endpoint MCP: http://<server>:8202/mcp. Pégalo en la config de tu cliente (ver docs/CLIENTS.md — Claude Code, Cursor, Continue, OpenCode, Hermes Gateway).

Opción B — stdio con Docker

La imagen ghcr.io/germaniu/mineru-mcp habla MCP por stdio y llama a un mineru-api que corre en el host. Configúrala en tu cliente MCP:

{  "mcpServers": {    "mineru": {      "command": "docker",      "args": [        "run", "-i", "--rm",        "--add-host", "host.docker.internal:host-gateway",        "-e", "MINERU_URL=http://host.docker.internal:8000",        "ghcr.io/germaniu/mineru-mcp:latest", "--stdio"      ]    }  }}

Dentro del contenedor file_path se refiere al sistema de archivos del contenedor: manda los documentos con file_base64 + file_name, o monta un directorio con -v. Sin systemd en el contenedor no hay wake-on-demand ni GPU Broker: mineru-api tiene que estar ya arriba.

Sin Docker: uvx --from git+https://github.com/GermaniU/mineru-mcp mineru-mcp --stdio, con uv ≥ 0.13.4 (config en docs/CLIENTS.md).

🔍 Diagnóstico

mineru_health dice si mineru-api responde, su versión y las tareas en cola, y distingue un backend dormido (detenido por inactividad) de uno roto. Se puede llamar sin cliente MCP, con el smoke test con curl.

⚙️ Configuración (Variables de Entorno)

Crea un archivo .env o exporta las siguientes variables:

Qué protege y qué no cada ajuste: SECURITY.md.

🛠️ Herramientas Expuestas (Tool Reference)

start_page y end_page cuentan desde 0: la demo pide start_page: 4, end_page: 5 y recibe las páginas 5 y 6 del paper. hybrid-engine + effort=high + image_analysis=true convierte figuras en diagramas Mermaid.

🎯 Alcance actual

MinerU MCP es deliberadamente delgado. Hace una cosa: llevar documentos de un cliente MCP a tu mineru-api y devolver el Markdown. El parseo lo hace MinerU.

Lo que SÍ hace

• ✅ PDF, DOCX, PPTX, XLSX, PNG y JPG a Markdown con títulos, tablas (HTML) y fórmulas (LaTeX).
• ✅ Recibe el documento como ruta del server (file_path) o como contenido (file_base64 + file_name) desde otra máquina.
• ✅ Parseo síncrono para documentos cortos y asíncrono con task_id para los largos, con rango de páginas.
• ✅ Si mineru-api está detenido y hay systemd, lo arranca (systemctl --user start, o sin --user con MINERU_SYSTEMCTL_SCOPE=system) y espera a que responda antes de parsear.
• ✅ Pide y devuelve la VRAM al GPU Broker cuando el host lo tiene.

Lo que NO hace (todavía)

• ❌ No incluye mineru-api ni los modelos. Se instalan aparte en el host, con sus servicios: docs/SERVER_SETUP.md.
• ❌ No manda documentos fuera de tu red. Si MINERU_URL no es loopback, se niega a enviarlos; no usa la API cloud de MinerU.
• ❌ No devuelve las imágenes extraídas, solo el Markdown.
• ❌ No hace streaming parcial del Markdown en extracciones largas: usa submit_parse_task y consulta el estado.
• ❌ No guarda documentos ni resultados. El archivo temporal del base64 se borra al terminar.
• ❌ En Docker no hay wake-on-demand ni GPU Broker: mineru-api tiene que estar arriba.

Si necesitas algo de la lista NO, abre un issue con un caso de uso real.

🧭 ¿Y los otros servidores MCP para documentos?

Hay tres familias, y resuelven problemas distintos.

En una frase:

• Si no tienes GPU ni servidor y no te importa subir los documentos → el MCP cloud oficial de MinerU.
• Si quieres un conversor que viva en la misma máquina que el cliente → Docling o MarkItDown.
• Si ya tienes (o quieres) MinerU en tu propio servidor y que los documentos no salgan de tu red, compartido por todos los clientes de la LAN → este.

🔌 Conectar tu cliente

Configuración lista para copiar en docs/CLIENTS.md (HTTP y stdio):

• 🟦 Claude Code — claude mcp add -s user -t http mineru http://<server>:8202/mcp (las tools aparecen en sesiones nuevas).
• 🟧 Cursor — Settings → MCP Servers → Add new MCP Server.
• 🟩 Continue (VS Code / JetBrains) — ~/.continue/config.json.
• 🟪 OpenCode — ~/.config/opencode/config.json.
• 🟨 Hermes Gateway — mcp_servers en ~/.hermes/config.yaml.
• 🟫 Claude Desktop — stdio con uvx o Docker, en la máquina de mineru-api.

Snippets listos en examples/.

🧪 Smoke test con curl

El modo HTTP es stateless: una sola request basta, sin initialize ni mcp-session-id.

curl -sS -X POST http://localhost:8202/mcp \  -H 'Content-Type: application/json' \  -H 'Accept: application/json, text/event-stream' \  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"mineru_health","arguments":{}}}'

Con MCP_AUTH_TOKEN añade -H "Authorization: Bearer <token>".

Para la prueba completa (health + parseo real de dos páginas de un paper de arXiv), la demo del GIF:

MCP_DEMO_URL=http://localhost:8202/mcp python scripts/demo_parse.py

🧱 Arquitectura

⚠️ Límites del sistema: mineru-mcp es únicamente la capa de transporte e interfaz MCP. No incluye el motor de procesamiento mineru-api ni la descarga en caché de modelos de HuggingFace.

 +-------------------------------------------------------+ |                 Clientes MCP (LAN)                    | | (Claude Code CLI / Cursor / Windsurf / Hermes Gateway)| +-------------------------------------------------------+                             |                             | HTTP / SSE (Puerto 8202)                             v +-------------------------------------------------------+ |                   mineru-mcp Server                   | |        (FastMCP + File Path / Base64 Decoder)         | +-------------------------------------------------------+                             |                             | Loopback HTTP (Puerto 8000)                             v +-------------------------------------------------------+ |                  MinerU Backend Host                  | |  (mineru-api + PDF-Extract-Kit + HuggingFace Cache)   | +-------------------------------------------------------+

Cada tool vive en src/mineru_mcp/tools/; server.py solo las registra en FastMCP y arranca el transporte. Detalle técnico en docs/ARCHITECTURE.md.

🤝 Contribuye

PRs, issues y forks bienvenidos (MIT).

Reglas (resumen):

1. Cambios chicos y directos. Toca el camino de código más angosto que explica el problema.
2. Sin abstracciones especulativas ni dependencias nuevas que no hagan falta.
3. Nombres y parámetros de las tools se preservan: los clientes dependen de ellos.
4. Identifiers en inglés, comentarios y commits en español. Conventional Commits (feat:, fix:, docs:, refactor:, test:, chore:).

Detalle completo en CONTRIBUTING.md.

uv venv && source .venv/bin/activateuv pip install -e ".[dev]"pytest          # unit tests, sin mineru-apiruff check .

🩹 Troubleshooting

mineru_health responde MinerU no disponible (el backend está inactivo)

• mineru-api está detenido (por ejemplo, por un watchdog de inactividad que devuelve la VRAM). No es un error: parse_document o submit_parse_task lo arrancan.

BLOQUEADO por seguridad: MINERU_URL apunta a …

• MINERU_URL no es loopback ni host.docker.internal. Es a propósito: los documentos no salen de tu máquina. Ver SECURITY.md.

MinerU no respondió tras 90s de arrancarlo o mineru_health dice inactivo con el backend arriba

• El scope no coincide con la unit: MINERU_SYSTEMCTL_SCOPE=user busca ~/.config/systemd/user/mineru-api.service y system busca /etc/systemd/system/mineru-api.service. Con user, el MCP tiene que correr en la sesión systemd del mismo usuario (por ejemplo, como unit de usuario). Ver docs/SERVER_SETUP.md.

MinerU no responde en … y aquí no hay systemd para arrancarlo

• Corres en Docker o macOS: no hay forma de despertar mineru-api. Arráncalo a mano y reintenta.

406 Not Acceptable al hacer curl al endpoint

• Falta el header Accept: application/json, text/event-stream.

401 {"error":"unauthorized"}

• El server tiene MCP_AUTH_TOKEN: manda Authorization: Bearer <token>.

Error: timeout. El documento puede ser muy grande

• Usa submit_parse_task y consulta con get_task_status, o parsea por rangos con start_page / end_page.

📚 Documentación

• docs/SERVER_SETUP.md — instalación de mineru-api, modelos y servicios en el host.
• docs/CLIENTS.md — config para Claude Code, Cursor, Continue, OpenCode, Hermes Gateway y Claude Desktop.
• docs/ARCHITECTURE.md — componentes, flujo de una petición y GPU Arbiter.
• SECURITY.md — modelo de amenazas y cómo reportar vulnerabilidades.
• CONTRIBUTING.md — entorno de desarrollo, reglas de estilo y flujo de trabajo.
• CHANGELOG.md — historial de cambios.

📄 Licencia

MIT — úsalo, fórkalo, mejóralo.

Hecho por @GermaniU. Si te sirvió, una ⭐ ayuda a que más gente lo encuentre. Si algo se rompió, abre un issue y lo arreglamos.