Carbone MCP

Carbone MCP Server

[npm version] [MCP Registry] [License: Apache-2.0]

Automate production-ready PDF, Word, Excel and PowerPoint documents from templates and JSON data, and convert files with 100+ conversions, from Claude, ChatGPT, Cursor, VS Code or any MCP client. The official server for the Carbone document generation API.

[Add to Claude] [Add to ChatGPT] [Add to Cursor] [Install in VS Code]

• Convert files: DOCX, XLSX, PPTX, HTML, SVG, Markdown or PDF to PDF, images, CSV, ODT and the other output formats.
• Fill templates with JSON: design them in Word, Excel, PowerPoint, LibreOffice, HTML or Markdown with {d.field} tags, or fill an existing PDF form.
• Finish your PDFs: passwords, watermarks, PDF/A, page ranges, and a choice of converter (LibreOffice, OnlyOffice, Chromium or Carbone ICE).
• Batch and localize: up to 100 documents per request, collected by the assistant on the hosted server or delivered to your own webhook; translations, time zones, and currency conversion at the rates you give.
• Keep a template library: upload, version, categorize, deploy and download templates, and ask which data a template expects.

What you can ask

Carbone turns data into finished documents, including data another MCP server fetches (Salesforce, HubSpot, Stripe, Notion, Google Sheets…) in the same conversation:

• "Get the Acme Corp opportunity and its products from Salesforce, fill my 'Sales quote' template, and give me a PDF with a DRAFT watermark."
• "Which data does my 'Service agreement' template expect? Map its fields to the HubSpot deal 'Acme renewal' and show me the JSON before you render it."
• "Create one certificate per attendee in the 'Workshop' Google Sheet with my 'Certificate' template, as a ZIP of PDFs named certificate-{d.lastName}."
• "Generate this invoice in French, German and Spanish, with prices converted from EUR to USD at 1.08 and dates in New York time."
• "Build a monthly report from last month's paid Stripe invoices with the 'Statement' template. Render it as a PNG first so you can check the layout, then give me the PDF."
• "Turn this Word quote into a Carbone template: add tags for the customer, a loop on the line items and the total, then upload it as 'Quote v2' in the 'sales' category."
• "Make a PDF/A copy of pages 1 to 5 of this contract for archiving, and a password-protected PDF with a CONFIDENTIAL watermark to send to the client."
• "Deploy the newest version of my 'Invoice' template, and schedule the old one for deletion in 30 days."

Account and pricing

You sign in with a Carbone account, free to create. Without a plan, you get unlimited watermarked PDFs. The Free plan adds every output format without a watermark, with 100 documents per month (pricing).

Quick start

Hosted server (mcp.carbone.io)

The Carbone agent plugin installs this server and the Carbone Skill together, in Claude, ChatGPT, Codex, Cursor, GitHub Copilot, Gemini CLI and more. To add the server alone:

Claude (claude.ai and Claude Desktop)

1. Open Carbone in the Claude directory and click Connect.
2. Sign in with your Carbone account and approve.

If your organization does not offer directory connectors, add a custom connector with the URL https://mcp.carbone.io instead, leaving the OAuth client ID and secret empty. In an organization, each member connects with their own Carbone account, and their documents count against it.

ChatGPT

Open the Carbone plugin in ChatGPT, click Add, then sign in with your Carbone account. The plugin also includes the Carbone Skill.

Without the plugin: open Plugins, click Add, then Add custom MCP server. Enter the name Carbone and the URL https://mcp.carbone.io, choose OAuth, tick I understand and want to continue, click Create as a plugin, and sign in.

Claude Code, VS Code, Cursor

Claude Code: add the server, then run /mcp, select carbone and choose Authenticate.

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

VS Code (.vscode/mcp.json), which asks you to sign in when it starts the server:

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

Cursor (~/.cursor/mcp.json or .cursor/mcp.json), then sign in from Cursor's MCP settings:

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

Local package (stdio)

Use it to read and save files on your computer. It needs Node.js 20.3 or later (node --version) and a Carbone API key from account.carbone.io: the test key makes unlimited watermarked PDFs (templates stored with it are kept 30 days), the production key every format (details).

Most clients use this config:

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

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 uses servers, not mcpServers. With an input variable, VS Code asks for the key once and stores it securely:

{  "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}" }    }  }}

Then try: "What can Carbone do?"

Client docs: Claude Desktop · Claude Code · VS Code · Cursor

Files in and out

• Hosted server: give files as HTTPS URLs or base64, or attach them in ChatGPT. A large template goes through an upload URL, for assistants that can run commands, such as Claude Code.
• Local package: absolute paths too (/Users/me/invoice.docx, ~/invoice.docx). A bare name such as invoice.docx is read as base64 and fails.
• Results: text and images come back in the conversation. PDF and Office files come back as a one-time download link (hosted, valid 1 hour) or a saved file (local).

Details: file inputs and output delivery.

Tools

Every parameter, with examples: docs/API.md.

Writing templates

Design a template in Word, Excel, PowerPoint, LibreOffice, HTML or Markdown, and put tags where the data goes:

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]} repeats a line for each item. Start with the basics, or give your AI assistant the Carbone Skill, a template syntax reference for AI tools (download .skill · GitHub).

Troubleshooting

Security

• Tool approval. Keep your client's approval prompts on for actions that change your account: delete_template deletes immediately, and update_template_metadata can schedule a deletion.
• Prompt injection. A document or template can contain instructions that trick the AI into unintended actions, such as sending data elsewhere or deleting templates. Review what your client is about to do before you confirm a tool call.
• Disconnecting. Disconnect the connector (in Claude Code, /mcp → Clear authentication) to stop the assistant from using your account.
• URL inputs and local files. URLs that resolve to a private or internal address (localhost, RFC 1918, cloud metadata) are refused unless CARBONE_ALLOW_PRIVATE_NETWORK=true (details). Local paths are read by the local package only, where the server runs as you.
• Shared server key (self-hosted HTTP). With CARBONE_API_KEY set on an HTTP server and CARBONE_REQUIRE_CLIENT_AUTH_HEADER=false (the default), every request without a Bearer key spends that key: anyone who can reach the port uses that Carbone account. The server prints a warning at startup. Never publish such a port on a network you don't fully trust, or set CARBONE_REQUIRE_CLIENT_AUTH_HEADER=true so each client must bring its own key.
• Browser origins (self-hosted HTTP). A request whose Origin header is present but not allowed gets 403, so a malicious web page cannot reach a locally running server (DNS rebinding) and spend its key. List the browser-based clients you trust in MCP_ALLOWED_ORIGINS.
• API keys. Keep them out of version control, pass them through your client's secret input or environment, and rotate them at account.carbone.io.
• Your data. Carbone stores the templates and samples you upload, and keeps a document delivered as a download link or to a webhook until it is downloaded, for 1 hour at most. For an async render, the server keeps an encrypted reference to the document for 1 hour. See the privacy policy, or run Carbone on-premise for full control.

Self-hosting

Docker

The image serves Streamable HTTP on port 3000. This quick start sets no server key: each client sends its own key in Authorization: Bearer <key> (signing in with a Carbone account is for mcp.carbone.io only), and the port is reachable from your machine only.

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

Connect your client with your key in the Authorization header. Claude Code:

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

VS Code (.vscode/mcp.json, which asks for the key once and stores it):

{  "inputs": [    { "type": "promptString", "id": "carbone-api-key", "description": "Carbone API key", "password": true }  ],  "servers": {    "carbone": {      "type": "http",      "url": "http://localhost:3000",      "headers": { "Authorization": "Bearer ${input:carbone-api-key}" }    }  }}

Cursor (~/.cursor/mcp.json), reading the key from your environment:

{  "mcpServers": {    "carbone": {      "url": "http://localhost:3000",      "headers": { "Authorization": "Bearer ${env:CARBONE_API_KEY}" }    }  }}

To serve other machines, publish the port behind a TLS reverse proxy, keep the server without CARBONE_API_KEY (or set CARBONE_REQUIRE_CLIENT_AUTH_HEADER=true), and list the hostnames of browser-based clients in MCP_ALLOWED_ORIGINS.

Shared-key variant, for one user on one machine. A server-level key lets clients connect without sending one. Read the shared-key warning first.

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

Docker Compose: compose.yml builds the image from this repository, binds 127.0.0.1 only, sets no server key, and passes through every variable of .env.example. Start it with docker compose up -d. Compose also reads CARBONE_API_KEY from your shell or a .env file: if it is set there, you get the shared-key variant.

To run the image as a stdio server for Claude Desktop, see the Docker Hub page.

On-premise Carbone

If you run Carbone on-premise, point the server at your instance with CARBONE_BASE_URL; no API key is needed. For example CARBONE_BASE_URL=https://your-carbone-server.com npx carbone-mcp, or add -e CARBONE_BASE_URL=https://your-carbone-server.com to docker run.

Configuration

Full descriptions: Configuration in docs/API.md.

Self-hosting troubleshooting

Upgrading from 1.x

HTTP deployments should upgrade now (security fixes): read the upgrade notes.

Contributing

Bug reports, fixes and documentation improvements are welcome. CONTRIBUTING.md covers the development setup, tests, debugging and the pull request process.

Support

• Documentation: MCP server · HTTP API · Template design · OpenAPI specification
• Bugs and feature requests: GitHub Issues
• Questions: live chat on carbone.io (bottom-right widget) · Enterprise: [email protected]

License

Apache 2.0, see LICENSE.