MinerU MCP

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.

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

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.git

cd mineru-mcp uv venv && source .venv/bin/activate uv pip install -e . MINERU_URL=http://127.0.0.1:8000 mineru-mcp

Endpoint MCP: http:// :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:// :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 ".

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