PDF to Markdown MCP Server

Servidor MCP (Model Context Protocol) que permite a asistentes de IA como Claude, Cursor y otros convertir archivos PDF a Markdown preservando el contexto completo de imágenes, tablas y código. Usa tecnología de IA avanzada con Gemini y LlamaParse para garantizar que ningún detalle visual o estructural se pierda en la conversión.

🌟 Características

• Conversión inteligente con preservación de contexto: No solo convierte texto, sino que extrae y describe imágenes, mantiene la estructura de tablas complejas, y preserva bloques de código con su formato original
• Imágenes contextualizadas: Cada imagen del PDF se analiza con IA y se describe en detalle, manteniendo su contexto en el documento
• Tablas complejas: Preserva la estructura exacta de tablas, incluyendo celdas combinadas y formato
• Código fuente: Mantiene bloques de código con su sintaxis y formato original
• Fácil integración: Compatible con Claude Desktop, Cursor, Windsurf y cualquier cliente MCP
• Sistema de créditos: Control de uso transparente
• API SaaS: Tu infraestructura en la nube, sin instalación local compleja

📦 Instalación

Opción 1: Uso directo con npx (Recomendado)

No necesitas instalar nada. Simplemente configura tu cliente MCP:

{
  "mcpServers": {
    "pdf-converter": {
      "command": "npx",
      "args": ["-y", "@manuesp/pdf-to-markdown-mcp"],
      "env": {
        "PDF_TO_MARKDOWN_API_KEY": "tu_api_key_aqui"
      }
    }
  }
}

Opción 2: Instalación global

npm install -g @manuesp/pdf-to-markdown-mcp

🔧 Configuración

Claude Desktop

1. Localiza tu archivo de configuración:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Añade el servidor MCP:

{
  "mcpServers": {
    "pdf-converter": {
      "command": "npx",
      "args": ["-y", "@manuesp/pdf-to-markdown-mcp"],
      "env": {
        "PDF_TO_MARKDOWN_API_KEY": "pk_live_tu_clave_aqui"
      }
    }
  }
}

3. Reinicia Claude Desktop

Cursor / Windsurf

Similar a Claude Desktop, configura en el archivo de configuración correspondiente del IDE.

🔑 Obtener API Key

1. Regístrate en tu-sitio-saas.com
2. Ve a tu dashboard de usuario
3. Copia tu API Key
4. Pégala en la configuración de tu cliente MCP

💡 Uso

Una vez configurado, simplemente interactúa con tu asistente de IA:

Ejemplos de comandos:

• "Convierte este PDF a Markdown: C:\Documentos\contrato.pdf"
• "Lee este informe y resume los puntos clave: ~/Downloads/informe-anual.pdf"
• "Extrae las tablas de este documento: /ruta/al/archivo.pdf"
• "Convierte este PDF y guarda el resultado en un archivo"

El servidor procesará el PDF y devolverá el contenido en Markdown junto con estadísticas del proceso.

📊 Respuesta del Servidor

Cuando conviertes un PDF recibirás:

• Contenido en Markdown: El texto completo extraído y formateado
• Estadísticas: Páginas procesadas, créditos usados
• Metadata: Información del documento

Ejemplo de respuesta:

✅ Conversión Completada Exitosamente

📊 Estadísticas del Documento:
- Archivo: contrato.pdf
- Tamaño: 2.34 MB
- Páginas procesadas: 15
- Créditos usados: 15
- Créditos restantes: 485

---

## Contenido en Markdown:
[El contenido del PDF en formato Markdown...]

🛠️ Desarrollo Local

Si quieres modificar o contribuir al servidor:

# Clonar el repositorio
git clone https://github.com/tu-usuario/pdf-to-markdown-mcp.git
cd pdf-to-markdown-mcp

# Instalar dependencias
npm install

# Compilar TypeScript
npm run build

# Probar localmente
PDF_TO_MARKDOWN_API_KEY=tu_key npm start

🔒 Seguridad

• API Key: Nunca compartas tu API Key públicamente
• Variables de entorno: La clave se configura como variable de entorno, no en código
• HTTPS: Todas las comunicaciones con la API usan cifrado TLS
• Sin almacenamiento: Los PDFs no se guardan permanentemente en el servidor

📝 Requisitos del Sistema

• Node.js: >= 18.0.0
• NPM: >= 8.0.0
• Sistema operativo: Windows, macOS, Linux

🐛 Solución de Problemas

Error: "PDF_TO_MARKDOWN_API_KEY no configurada"

Asegúrate de haber añadido la API Key en la configuración del cliente MCP.

Error: "Archivo no encontrado"

Verifica que la ruta al PDF sea absoluta y correcta. Usa rutas completas como:

• Windows: C:\\Users\\usuario\\documento.pdf
• macOS/Linux: /home/usuario/documento.pdf

Error: "Créditos insuficientes"

Tu cuenta ha agotado los créditos. Recarga en el dashboard de la plataforma.

Timeout

Si el PDF es muy grande (>50MB), puede tardar varios minutos. Espera o divide el documento.

📄 Licencia

MIT License - Libre para uso comercial y personal

🤝 Soporte

• Email: [email protected]
• Documentación: API Docs
• Issues: GitHub Issues

🚀 Roadmap

• [ ] Soporte para batch processing (múltiples PDFs)
• [ ] Opciones de configuración (idioma, formato de salida)
• [ ] Cache local para documentos ya procesados
• [ ] Webhooks para procesamiento asíncrono
• [ ] Soporte para imágenes embebidas

📚 Documentación Adicional

• INSTALLATION.md - Guía detallada de instalación
• QUICKSTART.md - Prueba rápida local antes de publicar
• TESTING.md - Guía completa de testing
• PUBLISHING.md - Cómo publicar en NPM y MCP Registry
• CHANGELOG.md - Historial de cambios

🏗️ Estructura del Proyecto

pdf-to-markdown-mcp/
├── src/
│   └── index.ts                 # Código fuente del servidor MCP
├── dist/                        # Código compilado (generado)
├── package.json                 # Configuración del paquete NPM
├── tsconfig.json               # Configuración de TypeScript
├── README.md                    # Este archivo
├── INSTALLATION.md             # Guía de instalación
├── QUICKSTART.md               # Inicio rápido
├── TESTING.md                  # Guía de testing
├── PUBLISHING.md               # Guía de publicación
├── CHANGELOG.md                # Historial de versiones
├── LICENSE                     # Licencia MIT
└── claude_desktop_config.example.json  # Ejemplo de configuración

Hecho con ❤️ para la comunidad MCP