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

Documentación

Servidor MCP de Carbone

Automatiza documentos PDF, Word, Excel y PowerPoint listos para producción a partir de plantillas y datos JSON, y convierte archivos entre 36 formatos, desde Claude, Cursor, VS Code o cualquier cliente MCP. El servidor oficial para la API de generación de documentos de Carbone.

Convierte archivos: DOCX, XLSX, PPTX, HTML, Markdown o PDF a PDF, imágenes, CSV, ODT y los demás formatos de salida.
Rellena plantillas con JSON: diséñalas en Word, Excel, PowerPoint, LibreOffice, HTML o Markdown con etiquetas {d.field}, o rellena un formulario PDF existente.
Termina tus PDFs: contraseñas, marcas de agua, PDF/A, rangos de páginas y una selección de convertidores (LibreOffice, OnlyOffice, Chromium o Carbone ICE).
Lotes y localización: hasta 100 documentos por solicitud, entregados a tu webhook; traducciones, zonas horarias y conversión de moneda a las tasas que tú indiques.
Mantén una biblioteca de plantillas: sube, versiona, categoriza, despliega y descarga plantillas, y pregunta qué datos espera una plantilla.

Lo que puedes preguntar

Estas funciones funcionan con cualquier cuenta de Carbone, incluso sin un plan (en ese caso obtienes PDFs con marca de agua):

"Convierte este Markdown a PDF: # Actualización trimestral …"
"Rellena mi plantilla de factura con este JSON y dame un PDF: {"customer": "Acme", "total": 1500}"
"¿Qué datos necesita esta plantilla de contrato?" (inspect_template lista sus etiquetas y redacta un JSON de muestra)

Más en Ejemplos de prompts, incluyendo con Salesforce, HubSpot, Notion y Stripe.

Inicio rápido

¿Actualizas desde 1.x? Lee las notas de actualización — los despliegues HTTP deberían actualizarse ahora (correcciones de seguridad).

Requisitos previos

Una cuenta de Carbone en account.carbone.io. El servidor alojado te permite iniciar sesión con ella y usa tu clave de producción una vez que tu cuenta tenga un plan (incluido el plan gratuito), y la clave de prueba hasta entonces. El paquete local y Docker usan una de las dos claves directamente (detalles):
- Clave de prueba: PDFs con marca de agua ilimitados, gratis (solo salida PDF). Las plantillas almacenadas con ella se conservan hasta 30 días.
- Clave de producción: cualquier formato de salida, sin marca de agua. El plan gratuito incluye 100 documentos al mes.
Node.js 20.3 o posterior para el paquete local (npx carbone-mcp). Verifícalo con node --version. La imagen Docker solo necesita Docker.

Elige una configuración

Configuración	Se ejecuta en	Clientes	Archivos locales
Servidor alojado (HTTP)	`https://mcp.carbone.io`, nada que instalar	claude.ai, Claude Desktop, Claude Code, VS Code, Cursor, …: inicia sesión con tu cuenta de Carbone	❌ Solo URLs y base64
Paquete local (stdio)	`npx carbone-mcp` en tu máquina	Claude Desktop, Claude Code, VS Code, Cursor y cualquier cliente que inicie servidores locales	✅ Lee rutas locales, guarda documentos en disco
Docker (HTTP)	Tu propio servidor	Clientes que puedan enviar un encabezado `Authorization`: Claude Code, VS Code, Cursor, …	❌ Solo URLs y base64

claude.ai y Claude Desktop: añade el servidor alojado como conector. En Claude Desktop, usa el paquete local para leer y guardar archivos en tu computadora.

Paquete local (stdio)

La mayoría de los clientes usan esta configuración:

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

Cliente	Dónde colocarlo
Claude Desktop	Configuración → Desarrollador → Editar configuración abre `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/`, Windows: `%APPDATA%\Claude\`). Sal y reinicia Claude Desktop después.
Cursor	`~/.cursor/mcp.json` (todos los proyectos) o `.cursor/mcp.json` (un proyecto)

Claude Code:

claude mcp add --env CARBONE_API_KEY=your_api_key_here --transport stdio carbone -- npx -y carbone-mcp

VS Code: .vscode/mcp.json usa servers, no mcpServers. Con una variable de entrada, VS Code pide la clave una vez y la almacena de forma segura:

{
  "inputs": [
    { "type": "promptString", "id": "carbone-api-key", "description": "Carbone API key", "password": true }
  ],
  "servers": {
    "carbone": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "carbone-mcp"],
      "env": { "CARBONE_API_KEY": "${input:carbone-api-key}" }
    }
  }
}

Luego prueba: "¿Qué puede hacer Carbone?"

Documentación de clientes: Claude Desktop · Claude Code · VS Code · Cursor

Servidor alojado (mcp.carbone.io)

Nada que instalar: conéctate a https://mcp.carbone.io a través de Streamable HTTP e inicia sesión con tu cuenta de Carbone cuando tu cliente abra account.carbone.io en tu navegador. A través de HTTP, las entradas de archivos deben ser URLs o base64 (Entradas de archivos).

Claude Code: añade el servidor, luego ejecuta /mcp, selecciona carbone y elige Autenticar.

claude mcp add --transport http carbone https://mcp.carbone.io

VS Code (.vscode/mcp.json), que te pide iniciar sesión cuando inicia el servidor:

{
  "servers": {
    "carbone": { "type": "http", "url": "https://mcp.carbone.io" }
  }
}

Cursor (~/.cursor/mcp.json o .cursor/mcp.json), luego inicia sesión desde la configuración de MCP de Cursor:

{
  "mcpServers": {
    "carbone": { "url": "https://mcp.carbone.io" }
  }
}

Conectores de claude.ai y Claude Desktop

Añade un conector personalizado con la URL https://mcp.carbone.io. Deja vacíos el ID de cliente OAuth y el secreto.
Haz clic en Conectar, inicia sesión con tu cuenta de Carbone y aprueba.

En una organización, cada miembro se conecta con su propia cuenta de Carbone, y sus documentos se contabilizan contra ella. Claude Desktop usa los mismos conectores; para leer y guardar archivos en tu computadora, usa el paquete local en su lugar.

Archivos de entrada y salida

Entradas de archivos

file (convert_document) y template (render_document, inspect_template, upload_template) aceptan:

Forma	Ejemplo	stdio	HTTP
Ruta local absoluta	`/Users/me/invoice.docx`, `~/invoice.docx`, `C:\Users\me\invoice.docx`	✅	❌ rechazada
URL	`https://example.com/invoice.docx`	✅	✅
Base64	el contenido del archivo, codificado en base64	✅	✅

Cualquier otra cadena, como un invoice.docx simple, se lee como base64 y falla. Las rutas relativas (./…, ../…) se resuelven contra el directorio de trabajo del servidor, que tu cliente elige: prefiere rutas absolutas. Los parámetros JSON (data, complement, …) también aceptan una ruta, URL o cadena base64 que apunte a un archivo JSON (detalles).

Entrega de salidas

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

En su lugar, puedes guardar en una ruta que elijas (outputPath, solo stdio), obtener un adjunto para cualquier formato (asAttachment) u obtener un enlace de descarga de un solo uso (returnLink): consulta Entrega de salidas y archivos.

Claude Desktop no puede mostrar adjuntos binarios en línea (los maneja incorrectamente como imágenes). Para archivos PDF y Office, mantén la ruta de archivo temporal predeterminada, o pide returnLink para obtener una URL de descarga.

Herramientas

Herramienta	Qué hace
`convert_document`	Convierte un archivo a otro formato; las etiquetas de Carbone se mantienen tal como están escritas
`render_document`	Rellena una plantilla con datos JSON y puede convertir el resultado (a PDF, por ejemplo)
`inspect_template`	Lista las etiquetas de una plantilla y devuelve un conjunto de datos de muestra correspondiente. Ejecuta una renderización en tu cuenta (cuenta como una generación de documento)
`list_templates`	Lista las plantillas almacenadas, filtradas por categoría, nombre o ID
`list_categories`	Lista las categorías de plantillas en tu cuenta
`list_tags`	Lista las etiquetas utilizadas en tus plantillas
`upload_template`	Almacena una plantilla reutilizable, con versiones, categoría y etiquetas
`update_template_metadata`	Renombra, categoriza, etiqueta, despliega o programa la eliminación de una versión de plantilla
`delete_template`	Elimina una plantilla o una de sus versiones, inmediatamente
`download_template`	Descarga el archivo original de una plantilla, o los datos de muestra almacenados con ella
`get_api_status`	Verifica el estado y la versión de la API de Carbone
`get_capabilities`	Resume los formatos, características y ejemplos de uso

Cada parámetro, con ejemplos: docs/API.md.

Ejemplos de prompts

Con tus otras herramientas. Carbone convierte datos que otro servidor MCP obtiene en un documento terminado. Estos asumen que ese servidor (Salesforce, HubSpot, Notion, Stripe, …) está conectado en el mismo cliente.

"Obtén la oportunidad de Acme Corp y sus productos de Salesforce, rellena mi plantilla 'Cotización de ventas' y dame el PDF"
"Para cada acuerdo de HubSpot que pasó a Cerrado Ganado esta semana, rellena la plantilla 'Acuerdo de servicio' y guarda los PDFs en ~/Contracts"
"Inspecciona mi plantilla 'Factura', mapea sus campos al acuerdo de HubSpot 'Renovación Acme' y muéstrame el JSON antes de renderizarlo"
"Recopila las tareas marcadas como Hechas en la base de datos 'Sprint 42' de Notion y rellena nuestra plantilla 'Informe de sprint' como DOCX"
"Lista las facturas pagadas de Stripe del mes pasado para Acme Corp y produce un estado de cuenta con la plantilla 'Estado'"
"Lee la lista de asistentes de la hoja de Google 'Taller' y crea un certificado por asistente a partir de la plantilla 'Certificado'"
"Resume los pull requests fusionados en GitHub esta semana en nuestra plantilla 'Notas de versión', luego publica un resumen de dos líneas en #releases en Slack"

Plantillas y datos

"Genera una factura a partir de la plantilla 1530905183164918624 con {customer: 'Acme Corp', total: 1500, items: [...]}"
"Rellena ~/templates/offer-letter.docx con ~/hr/jane-doe.json y guarda el PDF como ~/Documents/offer-jane-doe.pdf"
"Muéstrame la plantilla 1530905183164918624 como PDF con sus etiquetas aún visibles, para que pueda verificar el diseño"

Convertir

"Convierte /Users/me/contracts/contract.docx a PDF con el convertidor Carbone ICE"
"Convierte https://example.com/sales.xlsx a CSV separado por punto y coma"
"Renderiza este PDF como una miniatura PNG"

Lotes y localización

"Crea una factura por cliente en ~/data/invoices.json, como un ZIP de archivos nombrados invoice-{d.id}, entregado a mi webhook https://example.com/hook"
"Genera esta factura en francés, alemán y español a partir de la misma plantilla"
"Renderiza el informe con precios convertidos de EUR a USD a 1.08, y fechas en hora de Nueva York"

Opciones de PDF y biblioteca de plantillas

"Convierte este DOCX a un PDF con la contraseña de apertura 'secret123' y una marca de agua BORRADOR al 20% de opacidad"
"Haz una copia PDF/A-2b de las páginas 1 a 5 de este NDA para archivar"
"Despliega la versión más reciente de mi plantilla de factura y programa la eliminación de la anterior en 30 días"

Solución de problemas

Síntoma	Causa y solución
Error de herramienta `Authentication failed: …` (sin clave, o una clave que la API de Carbone rechaza con `401`)	stdio: establece `CARBONE_API_KEY` en el `env` de la configuración del cliente y reinicia el cliente (sin ello, el servidor se detiene al inicio con `CARBONE_API_KEY environment variable is required`). HTTP autohospedado: envía `Authorization: Bearer <key>`; un servidor con `CARBONE_REQUIRE_CLIENT_AUTH_HEADER=true` lo requiere en cada solicitud. Verifica la clave en account.carbone.io.
mcp.carbone.io te pide iniciar sesión de nuevo, o el inicio de sesión falla	Reconecta: en Claude, Desconectar y luego Conectar el conector; en Claude Code, `/mcp` → Borrar autenticación, luego Autenticar.
HTTP `403` `Invalid Origin: <host>`	Un cliente basado en navegador servido desde un host distinto a `localhost`. Añade su nombre de host a `MCP_ALLOWED_ORIGINS`.
HTTP `405` `Method not allowed` al abrir el endpoint en un navegador	Esperado: el endpoint solo responde a solicitudes MCP `POST`. Conéctate con un cliente MCP; verifica el servidor con `GET /health`.
HTTP `413` `Request body too large`, o la conexión stdio se cierra	Un mensaje MCP supera `MCP_MAX_BODY_BYTES` (60 MB por defecto; aplica también a mensajes stdio). Pasa archivos grandes por URL (o una ruta local en stdio) en lugar de base64 en línea, o aumenta el límite.
`Rate limit exceeded. Please wait N second(s)`	La API de Carbone respondió `429`. Espera el tiempo indicado e inténtalo de nuevo.
Etiquetas como `{d.name}` aún visibles en la salida	`convert_document` es una conversión pura y conserva las etiquetas. Usa `render_document` con tus datos.
Marca de agua en cada PDF, o solo funciona PDF	Usas la clave de prueba: produce solo PDFs con marca de agua. En mcp.carbone.io, inicia un plan en account.carbone.io (el plan Gratuito es suficiente): el servidor cambia a tu clave de producción automáticamente. Localmente, usa la clave de producción.
Un archivo dado por nombre (`invoice.docx`) falla	Un nombre simple se lee como base64. Pasa una ruta absoluta (stdio), una URL o base64 (Entradas de archivo).
El renderizado por ID de plantilla aún usa la versión antigua tras una subida	Los renderizados por ID de plantilla usan la versión desplegada (la más reciente `deployedAt`). Despliega la nueva versión con `update_template_metadata` (`templateId` = su ID de versión, `deployedAt` = `42000000000`), o renderiza por ID de versión.
Contraseña, marca de agua o PDF/A ausentes en un PDF	PDF/A, rangos de páginas y accesibilidad usan el convertidor predeterminado `L` (LibreOffice); `O`, `C` y `I` aplican contraseñas, permisos y marcas de agua. Para PDF → PDF el servidor establece `hardRefresh` por ti: no pases `hardRefresh: false`.
Claude Desktop no muestra herramientas de Carbone, o el servidor se desconecta	Lee `mcp-server-carbone.log` (el stderr del servidor) en `~/Library/Logs/Claude/` (macOS) o `%APPDATA%\Claude\logs\` (Windows). Un buen inicio registra `Carbone MCP Server v<version> started (stdio)`.
Quieres probar el servidor sin un cliente de IA	Ejecuta el Inspector MCP (Node.js 22.19+): `npx @modelcontextprotocol/inspector -e CARBONE_API_KEY=your_api_key_here npx carbone-mcp`. Lista las herramientas y muestra cada solicitud y respuesta.

Autohospedaje

Docker

La imagen sirve Streamable HTTP en el puerto 3000. Este inicio rápido no establece clave de servidor: cada cliente envía su propia clave en Authorization: Bearer <key> (iniciar sesión con una cuenta de Carbone es solo para mcp.carbone.io), y el puerto es accesible solo desde tu máquina.

docker run -d --name carbone-mcp -p 127.0.0.1:3000:3000 carbone/carbone-mcp
curl http://localhost:3000/health

Conecta tu cliente con tu clave en el encabezado Authorization:

claude mcp add --transport http carbone http://localhost:3000 --header "Authorization: Bearer your_api_key_here"

En VS Code y Cursor, toma la configuración de servidor alojado con la URL http://localhost:3000 y añade "headers": { "Authorization": "Bearer your_api_key_here" } junto a "url". VS Code puede solicitar la clave con una entrada inputs de tipo promptString ("Bearer ${input:carbone-api-key}"), y Cursor puede leerla de tu entorno ("Bearer ${env:CARBONE_API_KEY}"). Para servir a otras máquinas, publica el puerto detrás de un proxy inverso TLS, mantén el servidor sin CARBONE_API_KEY (o establece CARBONE_REQUIRE_CLIENT_AUTH_HEADER=true), y lista los hostnames de clientes basados en navegador en MCP_ALLOWED_ORIGINS.

Variante de clave compartida, para un usuario en una máquina. Una clave a nivel de servidor permite que los clientes se conecten sin enviar una:

docker run -d --name carbone-mcp -p 127.0.0.1:3000:3000 -e CARBONE_API_KEY=your_api_key_here carbone/carbone-mcp

Lee la advertencia de clave compartida antes de usarla.

Docker Compose: compose.yml construye la imagen desde este repositorio, vincula solo 127.0.0.1, no establece clave de servidor, y pasa cada variable de .env.example. Inícialo con docker compose up -d. Compose también lee CARBONE_API_KEY de tu shell o un archivo .env: si está establecido allí, obtienes la variante de clave compartida.

Para ejecutar la imagen como servidor stdio para Claude Desktop, consulta la página de Docker Hub.

Carbone on-premise

Si ejecutas Carbone on-premise, apunta el servidor a tu instancia con CARBONE_BASE_URL; no se necesita clave API. Por ejemplo CARBONE_BASE_URL=https://your-carbone-server.com npx carbone-mcp, o añade -e CARBONE_BASE_URL=https://your-carbone-server.com a docker run.

Configuración

Variable	Predeterminado	Propósito
`CARBONE_API_KEY`	ninguno	Tu clave API de Carbone: requerida en stdio para Carbone Cloud, opcional sobre HTTP (Seguridad)
`CARBONE_BASE_URL`	`https://api.carbone.io`	URL de la API de Carbone; establécelo a una instancia on-premise (sin clave necesaria)
`CARBONE_TIMEOUT`	`60000`	Tiempo de espera de solicitud de la API de Carbone en ms; el límite propio de Carbone Cloud es 60 s
`CARBONE_MAX_FILE_BYTES`	`104857600` (100 MB)	Archivo de entrada más grande leído desde una ruta, URL o base64
`MCP_TRANSPORT`	`stdio` (`http` en Docker)	`stdio` o `http`
`MCP_PORT`	`3000`	Puerto HTTP
`MCP_PATH`	`/`	Ruta del endpoint HTTP; no puede ser `/health`
`MCP_MAX_BODY_BYTES`	`62914560` (60 MB)	Mensaje MCP más grande: un cuerpo HTTP (`413` por encima de él) o un mensaje stdio
`MCP_ALLOWED_ORIGINS`	ninguno (localhost siempre está permitido)	HTTP: hostnames de navegador `Origin` a permitir, separados por comas
`CARBONE_REQUIRE_CLIENT_AUTH_HEADER`	`false`	HTTP: `true` rechaza solicitudes que no traen una clave Bearer propia
`CARBONE_ALLOW_PRIVATE_NETWORK`	`false`	`true` permite que las entradas URL alcancen direcciones privadas e internas

Descripciones completas: Configuración en docs/API.md.

Seguridad

Entradas URL y archivos locales. Las URLs que resuelven a una dirección privada o interna (localhost, RFC 1918, metadatos de nube) se rechazan a menos que CARBONE_ALLOW_PRIVATE_NETWORK=true (detalles). Las rutas locales se leen solo en stdio, donde el servidor se ejecuta como tú; sobre HTTP se rechazan.
Clave de servidor compartida (HTTP). Con CARBONE_API_KEY establecido en un servidor HTTP y CARBONE_REQUIRE_CLIENT_AUTH_HEADER=false (el predeterminado), cada solicitud sin clave Bearer gasta esa clave: cualquiera que pueda alcanzar el puerto usa esa cuenta de Carbone. El servidor imprime una advertencia al inicio. Nunca publiques tal puerto en una red que no confíes completamente, o establece CARBONE_REQUIRE_CLIENT_AUTH_HEADER=true para que cada cliente deba traer su propia clave. Esto no aplica cuando no se establece clave de servidor (por ejemplo, Carbone on-premise sin autenticación).
Orígenes de navegador (HTTP). Una solicitud cuyo encabezado Origin está presente pero no permitido obtiene 403, por lo que una página web maliciosa no puede alcanzar un servidor local (DNS rebinding) y gastar su clave. localhost, 127.0.0.1 y [::1] están permitidos; lista los clientes basados en navegador que confíes en MCP_ALLOWED_ORIGINS. Las solicitudes sin Origin (clientes de escritorio, CLI y servidor) no se ven afectadas.
Inyección de prompts. Un documento o plantilla puede contener instrucciones que engañen a la IA para acciones no intencionadas, como enviar datos a otro lugar o eliminar plantillas. Revisa lo que tu cliente está a punto de hacer antes de confirmar una llamada de herramienta.
Claves API. Mantenlas fuera del control de versiones, pásalas a través de la entrada secreta de tu cliente o entorno, y rótalas en account.carbone.io.
Tus datos. Carbone almacena las plantillas y muestras que subes, y mantiene documentos renderizados con returnLink o un webhook hasta que se descargan. Consulta la política de privacidad, o ejecuta Carbone on-premise para control total.

Escribir plantillas

Diseña una plantilla en Word, Excel, PowerPoint, LibreOffice, HTML o Markdown, y coloca etiquetas donde van los datos:

Dear {d.customer.name},
Your invoice total is {d.total:formatC()}.
Items:
{d.items[i].description}  {d.items[i].quantity}x  {d.items[i].price:formatC()}
{d.items[i+1]}

{d.items[i]} … {d.items[i+1]} repite una línea por cada elemento. Comienza con los conceptos básicos, o da a tu asistente de IA la Habilidad Carbone, una referencia de sintaxis de plantillas para herramientas de IA (descargar .skill · GitHub).

Contribuir

Los informes de errores, correcciones y mejoras de documentación son bienvenidos. CONTRIBUTING.md cubre la configuración de desarrollo, pruebas, depuración y el proceso de solicitudes de extracción.

Soporte

Documentación: Servidor MCP · API HTTP · Diseño de plantillas · Especificación OpenAPI
Errores y solicitudes de funciones: Problemas de GitHub
Preguntas: chat en vivo en carbone.io (widget inferior derecho) · Empresa: contact@carbone.io

Licencia

Apache 2.0, consulta LICENCIA.