Carbone

Servidor MCP universal de generación y conversión de documentos. Genera PDF/DOCX/XLSX a partir de plantillas+JSON (facturas, contratos, informes), generación por lotes, más de 100 conversiones de formato.

GitHub

Prueba este MCPPatrocinado

Documentación

Servidor MCP de Carbone

Servidor MCP oficial de Carbone — Convierte asistentes de IA en expertos en automatización de documentos. Genera PDFs profesionales, facturas, informes y más usando lenguaje natural.

Dale a Claude, ChatGPT y otros asistentes de IA el poder de:

🔄 Conversión de documentos — Más de 100 combinaciones de formatos (PDF, DOCX, XLSX, PNG, HTML, CSV…)
📄 Motor de plantillas — Genera documentos a partir de datos JSON con etiquetas {d.field}
📚 Biblioteca de plantillas — Sube, versiona, categoriza y gestiona plantillas reutilizables
🎨 Personalización de PDF — Rellena formularios PDF, añade marcas de agua, contraseñas, cifrado, múltiples motores de conversión (LibreOffice, OnlyOffice, Chromium, Carbone ICE)
🌍 Localización — Soporte multilingüe, conversión de moneda, gestión de zonas horarias
⚡ Generación por lotes — Crea cientos de documentos en una sola solicitud (asíncrono vía webhook)

Instalación

Obtén tu clave API gratuita en account.carbone.io.

stdio — Claude Desktop, VS Code, Cursor, Claude Code y más

Todos los clientes MCP compatibles con stdio usan la misma configuración:

{
  "mcpServers": {
    "carbone": {
      "command": "npx",
      "args": ["-y", "carbone-mcp"],
      "env": {
        "CARBONE_API_KEY": "your_api_key_here"
      }
    }
  }
}

Cliente	Archivo de configuración
Claude Desktop (macOS)	`~/Library/Application Support/Claude/claude_desktop_config.json`
Claude Desktop (Windows)	`%APPDATA%\Claude\claude_desktop_config.json`
Cursor (global)	`~/.cursor/mcp.json`
Cursor (proyecto)	`.cursor/mcp.json`
Claude Code	`claude mcp add carbone-mcp -e CARBONE_API_KEY=your_key -- npx -y carbone-mcp`

VS Code usa { "mcp": { "servers": { ... } } } en lugar de { "mcpServers": { ... } } — el bloque de configuración interno es idéntico.

Después de añadir la configuración, reinicia tu cliente y prueba: "¿Qué puede hacer Carbone?"

HTTP — mcp.carbone.io (sin instalación local)

Conéctate directamente al endpoint alojado. Compatible con VS Code, Cursor, Claude Code y otros clientes que soportan transporte HTTP transmisible.

{
  "mcp": {
    "servers": {
      "carbone": {
        "type": "streamable-http",
        "url": "https://mcp.carbone.io",
        "headers": {
          "Authorization": "Bearer your_api_key_here"
        }
      }
    }
  }
}

Autenticación: El endpoint HTTP actualmente requiere una clave API de Carbone pasada como token Bearer en el encabezado Authorization. El soporte OAuth2 (para Claude Desktop, Mistral, ChatGPT, Gemini y otros clientes) está planificado para una futura versión.

Cursor usa { "mcpServers": { ... } } en lugar de { "mcp": { "servers": { ... } } } — el bloque de configuración interno es idéntico.

Claude Desktop no soporta autenticación con token Bearer HTTP — usa la opción stdio anterior en su lugar.

Docker — servidor HTTP autoalojado

docker run -d -p 3000:3000 \
  -e MCP_TRANSPORT=http \
  -e CARBONE_API_KEY=your_api_key_here \
  carbone/carbone-mcp

Conecta tu cliente MCP a http://your-host:3000 usando la configuración HTTP anterior (reemplaza la URL).

Docker Compose — consulta compose.yml:

CARBONE_API_KEY=your_key docker compose up -d

Claude Desktop con Docker (stdio) — Claude Desktop no soporta transporte HTTP; usa el modo stdio en su lugar:

{
  "mcpServers": {
    "carbone": {
      "command": "docker",
      "args": ["run", "-i", "--rm",
               "-e", "CARBONE_API_KEY=your_api_key_here",
               "-e", "MCP_TRANSPORT=stdio",
               "carbone/carbone-mcp"]
    }
  }
}

On-Premise — instancia de Carbone autoalojada

Si ejecutas Carbone on-premise, apunta el servidor MCP a tu instancia — no se requiere clave API:

# Docker (HTTP)
docker run -d -p 3000:3000 \
  -e CARBONE_BASE_URL=https://your-carbone-server.com \
  carbone/carbone-mcp

# stdio
CARBONE_BASE_URL=https://your-carbone-server.com npx carbone-mcp

Variables de entorno

Requeridas (modo stdio, API en la nube):

CARBONE_API_KEY — Tu clave API de Carbone (obtén una gratis →). No requerida cuando CARBONE_BASE_URL apunta a tu propio servidor on-premise, o cuando se ejecuta en modo HTTP (los clientes proporcionan su propia clave vía Authorization: Bearer).

Configuración opcional

Variable	Predeterminado	Descripción
`CARBONE_BASE_URL`	`https://api.carbone.io`	Anulación para entornos autoalojados o de staging. Cuando se establece una URL personalizada, `CARBONE_API_KEY` no es requerida.
`CARBONE_TIMEOUT`	`60000`	Tiempo de espera de solicitud en milisegundos (máx: 60000)
`CARBONE_MAX_FILE_BYTES`	`104857600`	Tamaño máximo (bytes) para un archivo de entrada resuelto — ruta, URL o base64 (100 MB por defecto)
`MCP_TRANSPORT`	`stdio`	Modo de transporte: `stdio` (predeterminado, para clientes de IA) o `http` (para despliegues autoalojados)
`MCP_PORT`	`3000`	Puerto del servidor HTTP (solo se usa cuando `MCP_TRANSPORT=http`)
`MCP_PATH`	`/`	Ruta del endpoint HTTP (solo se usa cuando `MCP_TRANSPORT=http`)
`MCP_MAX_BODY_BYTES`	`62914560`	Tamaño máximo del cuerpo de solicitud en bytes (60 MB por defecto, coincidiendo con el límite de Carbone Cloud)
`CARBONE_REQUIRE_CLIENT_AUTH_HEADER`	`false`	Solo modo HTTP — requiere `Authorization: Bearer <key>` en cada solicitud. Deja `false` solo si pretendes un servidor de clave compartida: con un `CARBONE_API_KEY` a nivel de servidor establecido, las solicitudes que no llevan clave Bearer recurren a él, por lo que cualquiera que pueda alcanzar el puerto puede gastar esa cuenta de Carbone. Establécelo en `true` para requerir que cada cliente traiga su propia clave. Irrelevante cuando no se establece clave de servidor (p. ej. on-premise)
`CARBONE_ALLOW_PRIVATE_NETWORK`	`false`	Permite que las URLs proporcionadas por el usuario (plantillas, `data`, …) se resuelvan a direcciones privadas/internas. Desactivado por defecto para bloquear SSRF (metadatos de nube, `localhost`, RFC1918). Actívalo solo en un despliegue de confianza con hosts de plantillas internos

Herramientas disponibles

Operaciones de documentos

Herramienta	Descripción	Docs
`convert_document`	Convierte documentos entre más de 100 formatos sin almacenar una plantilla	→
`render_document`	Genera documentos a partir de plantillas combinándolas con datos JSON	→

Gestión de plantillas

Herramienta	Descripción	Docs
`list_templates`	Explora tu biblioteca de plantillas con filtrado por categoría o búsqueda (las etiquetas se devuelven por plantilla pero no se pueden filtrar en el servidor)	→
`list_categories`	Lista todas las categorías de plantillas en tu cuenta	→
`list_tags`	Lista todas las etiquetas usadas en tus plantillas	→
`upload_template`	Almacena plantillas reutilizables con versionado, categorización y metadatos	→
`update_template_metadata`	Renombra, categoriza, etiqueta, despliega o expira versiones de plantillas	→
`delete_template`	Eliminación suave de plantillas (marcadas para eliminación, desaparecen después de ~24h)	→
`download_template`	Descarga archivos de plantilla originales (DOCX, XLSX, PDF, etc.)	→

Descubrimiento

Herramienta	Descripción	Docs
`get_api_status`	Comprueba el estado de la API de Carbone y la versión actual
`get_capabilities`	Consulta todos los formatos, características y ejemplos soportados

📖 Referencia completa de la API → — Parámetros, esquemas y ejemplos detallados

Salida y entrega de archivos

Por defecto, un archivo generado o convertido se devuelve según su tipo y transporte:

Salida	stdio (clientes locales)	HTTP (remoto / autoalojado)
Texto — HTML, TXT, CSV, MD, XML	texto en línea	texto en línea
Imágenes en línea — PNG, JPG, GIF, WEBP	imagen en línea	imagen en línea
Todo lo demás — PDF, Office, ZIP, SVG…	guardado en un archivo temporal, se devuelve la ruta	devuelto como adjunto de descarga

Tres parámetros opcionales en convert_document y render_document (y outputPath / asAttachment en download_template) anulan esto:

Parámetro	Efecto
`outputPath`	Solo stdio — guarda la salida en esta ruta local en lugar de devolverla en línea (rechazado en modo HTTP)
`asAttachment`	devuelve los bytes como adjunto descargable para cualquier formato, en lugar de en línea
`returnLink`	devuelve la URL de descarga pública de un solo uso de Carbone en lugar del archivo — de corta duración y consumida por la primera descarga, así que entrégala al usuario en lugar de obtenerla tú mismo (funciona en stdio y HTTP)

Claude Desktop: no puede renderizar adjuntos binarios en línea (los maneja incorrectamente como imágenes). Para PDFs y archivos de Office, confía en la ruta de archivo temporal predeterminada de stdio, o usa returnLink para obtener una URL de descarga.

Casos de uso comunes

📄 Conversión de documentos

"Convert this Word document to PDF: /path/to/contract.docx"
"Turn my Excel spreadsheet into CSV format"
"Convert this HTML page to a PNG image"
"Convert my Markdown README to PDF"
"Convert this PPTX to PNG — use OnlyOffice for best fidelity"
"Convert this 500-page Word report to PDF — use the ICE converter, it's much faster"
"Rasterize this PDF to PNG images — one per page"

💼 Finanzas y facturación

"Generate an invoice using template T123 with: {customer: 'Acme Corp', total: 1500, items: [...]}"
"Generate invoices from the data in /data/invoices.json"
"Create 500 invoices from my billing data and bundle them in a ZIP"
"Generate a French invoice for my Paris client — use EUR currency and fr-fr locale"
"Render this monthly report for each client in clients.json and ZIP them all"
"Generate invoice-{d.id}.pdf for each row in my sales data"

⚖️ Legal y cumplimiento

"Add a CONFIDENTIAL watermark to this contract before sending it"
"Convert this NDA to PDF/A format for long-term archiving"
"Generate a password-protected PDF — open password: 'secret123'"
"Create signed offer letters for each candidate using this DOCX template"
"Generate a compliance report with a DRAFT watermark, 20% opacity, rotated -45°"

👥 RR. HH. y operaciones de personal

"Create personalized onboarding documents for all 50 new employees in this JSON"
"Generate an employment contract for each person in new-hires.json"
"Build payslips for every employee in my payroll export"
"Create training certificates for everyone who passed this month"
"Fill out the performance review template with each employee's data"

🌍 Localización y multilingüe

"Generate this invoice in French, German, and Spanish from the same template"
"Render the report with timezone America/New_York so dates show in Eastern time"
"Convert all prices from EUR to USD using today's exchange rates"
"Generate the contract in fr-fr locale so numbers use European formatting"

🔐 Seguridad PDF y opciones avanzadas

"Convert this DOCX to a password-protected PDF"
"Add a semi-transparent DRAFT watermark to every page"
"Generate a PDF/A-1b compliant version of this document for archiving"
"Export only pages 1–5 of this presentation as a PDF"
"Convert each slide of this PPTX to a separate PDF page"

📚 Gestión de plantillas

"Upload this invoice template and tag it 'sales' and 'finance'"
"What templates do I have in the 'contracts' category?"
"Show me all templates tagged 'hr'"
"Download template T456 so I can edit it locally"
"Deploy version V789 as the active version without deleting the others"
"Schedule this old template for deletion in 30 days"

Depuración

Usando MCP Inspector

Prueba y depura el servidor de forma interactiva:

npx @modelcontextprotocol/inspector npx carbone-mcp

O desde una compilación local:

npx @modelcontextprotocol/inspector node dist/index.js

Abre http://localhost:5173 para ver todas las herramientas, probar llamadas e inspeccionar el JSON de solicitud/respuesta — no se necesita inferencia de IA.

Ver registros del servidor

# macOS — Claude Desktop logs
tail -f ~/Library/Logs/Claude/mcp*.log

# Windows
Get-Content "$env:APPDATA\Claude\logs\mcp*.log" -Wait -Tail 50

Busca:

✅ Carbone MCP Server v1.x.x started (stdio)
❌ Cualquier mensaje de error o trazas de pila

Comprobación de estado (solo modo HTTP)

Cuando se ejecuta en modo HTTP, el servidor expone un endpoint de estado:

curl http://localhost:3000/health

{
  "mcp":    { "version": "1.2.2" },
  "carbone": { "version": "5.x.x" }
}

El campo carbone muestra la conectividad del backend:

{ "version": "..." } — accesible y autenticado
{ "error": "unauthorized", "message": "..." } — accesible pero sin clave API o clave no válida
{ "error": "unreachable", "message": "..." } — error de red, tiempo de espera o respuesta inesperada

Seguridad

⚠️ Entradas de archivos y URLs (SSRF / archivos locales) Las herramientas aceptan una ruta local, una URL HTTPS o base64 para file / template y los parámetros JSON por referencia (data, complement, …). Se aplican dos protecciones:

Las URLs se resuelven y se rechazan cuando apuntan a direcciones de loopback, privadas (RFC1918), link-local (incl. metadatos de nube 169.254.169.254), CGNAT o reservadas — y cada salto de redirección se vuelve a comprobar. Establece CARBONE_ALLOW_PRIVATE_NETWORK=true solo en un despliegue de confianza que necesite hosts de plantillas internos.
Las rutas locales son legibles solo en stdio, donde el servidor ya se ejecuta como tú. En modo HTTP se rechazan, por lo que un llamador remoto nunca puede hacer que el servidor lea su propio sistema de archivos.

⚠️ Compartir una clave API a nivel de servidor (modo HTTP) Si estableces CARBONE_API_KEY en un servidor HTTP y dejas CARBONE_REQUIRE_CLIENT_AUTH_HEADER=false (el predeterminado), las solicitudes sin clave Bearer recurren a esa clave — cualquiera que pueda alcanzar el puerto puede gastar esa cuenta de Carbone. Establécelo en true para requerir que cada cliente traiga su propia clave, o expón el puerto solo en una red de confianza. (No aplicable cuando no se establece clave de servidor, p. ej. Carbone on-premise sin autenticación.)

⚠️ Inyección de prompts Conectar un asistente de IA a cualquier servicio externo conlleva riesgos inherentes. Un documento o plantilla malicioso podría contener instrucciones que engañen a la IA para realizar acciones no deseadas (p. ej. exfiltrar datos, eliminar plantillas). Siempre revisa lo que tu cliente de IA está a punto de hacer antes de confirmar llamadas a herramientas.

⚠️ Protección de la clave API

Nunca hagas commit de CARBONE_API_KEY en el control de versiones
Usa variables de entorno o un gestor de secretos
Rota las claves API regularmente en account.carbone.io

⚠️ Seguridad de plantillas

Solo sube plantillas de fuentes de confianza
Revisa las plantillas antes de desplegarlas
Usa el versionado de plantillas para una reversión fácil

⚠️ Privacidad de datos

Carbone no almacena tus datos de documentos después del renderizado
Usa CARBONE_BASE_URL para apuntar a una instancia autoalojada para máximo control
Consulta la Política de privacidad para más detalles

Sintaxis de plantillas

Diseña plantillas en Word, Excel, LibreOffice o HTML con etiquetas {d.field}:

Dear {d.customer.name},

Your invoice total is {d.total:formatC(EUR)}.

Items:
{d.items[i].description}  {d.items[i].quantity}x  {d.items[i].price:formatC(EUR)}
{d.items[i+1]}

Guías y mejores prácticas:

Carbone Skill — Referencia de sintaxis universal de plantillas Carbone para herramientas de IA (descargar .skill · GitHub)
Sintaxis de plantillas
Guía de plantillas HTML
Guía de plantillas Markdown

Formatos de salida soportados

Categoría	Formatos
Documentos	PDF, DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, RTF, EPUB
Imágenes	PNG, JPG, WEBP, SVG, TIFF, BMP, GIF
Web / Texto	HTML, TXT, CSV, MD, XML

Matriz de conversión completa: carbone.io/documentation

Contribuciones

Damos la bienvenida a las contribuciones:

🐛 Reporta errores vía GitHub Issues
💡 Solicita funciones o sugiere mejoras
📝 Mejora la documentación
🧪 Añade pruebas para aumentar la cobertura
🔧 Envía pull requests con correcciones de errores o mejoras

Consulta CONTRIBUTING.md para las pautas.

Desarrollo

npm run dev          # Run with tsx (no build needed)
npm run build        # Compile TypeScript → dist/
npm test             # Run the test suite (integration tests run only with CARBONE_TEST_API_KEY)
npm run test:watch   # Watch mode
npm run test:integration  # Real API tests (requires CARBONE_TEST_API_KEY)
npm run test:coverage     # Coverage report

Soporte

🤖 Documentación de MCP: carbone.io/documentation/developer/ai/mcp.html
📚 Documentación de la API: carbone.io/documentation/developer/http-api/introduction.html
📚 Documentación de plantillas: carbone.io/documentation/design/overview/getting-started.html
🐛 Informes de errores: GitHub Issues
💬 Chat en vivo: carbone.io (widget en la esquina inferior derecha)
📧 Empresas: contact@carbone.io
📋 Especificación OpenAPI: carbone.OpenAPI.yml

Licencia

Apache 2.0 — consulte LICENSE