Carbone MCP Server

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

• Convert files: DOCX, XLSX, PPTX, HTML, 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, delivered to your 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

These work on any Carbone account, even without a plan (you then get watermarked PDFs):

• "Convert this Markdown to PDF: # Quarterly update …"
• "Fill my invoice template with this JSON and give me a PDF: {"customer": "Acme", "total": 1500}"
• "Which data does this contract template need?" (inspect_template lists its tags and drafts a sample JSON)

More in Example prompts, including with Salesforce, HubSpot, Notion and Stripe.

Quick start

Upgrading from 1.x? Read the upgrade notes — HTTP deployments should upgrade now (security fixes).

Prerequisites

• A Carbone account at account.carbone.io. The hosted server signs you in with it and uses your production key once your account has a plan (the Free plan included), the test key until then. The local package and Docker use one of the two keys directly (details):
• Test key: unlimited watermarked PDFs, free (PDF output only). Templates stored with it are kept for up to 30 days.
• Production key: any output format, no watermark. The Free plan includes 100 documents per month.
• Node.js 20.3 or later for the local package (npx carbone-mcp). Check with node --version. The Docker image needs Docker only.

Choose a setup

claude.ai and Claude Desktop: add the hosted server as a connector. In Claude Desktop, use the local package instead to read and save files on your computer.

Local package (stdio)

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

Hosted server (mcp.carbone.io)

Nothing to install: connect to https://mcp.carbone.io over Streamable HTTP, and sign in with your Carbone account when your client opens account.carbone.io in your browser. Over HTTP, file inputs must be URLs or base64 (File inputs).

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

claude.ai and Claude Desktop connectors

1. Add a custom connector with the URL https://mcp.carbone.io. Leave the OAuth client ID and secret empty.
2. Click Connect, sign in with your Carbone account and approve.

In an organization, each member connects with their own Carbone account, and their documents count against it. Claude Desktop uses the same connectors; to read and save files on your computer, use the local package instead.

Files in and out

File inputs

file (convert_document) and template (render_document, inspect_template, upload_template) accept:

Any other string, such as a bare invoice.docx, is read as base64 and fails. Relative paths (./…, ../…) resolve against the server's working directory, which your client chooses: prefer absolute paths. The JSON parameters (data, complement, …) also accept a path, URL or base64 string pointing to a JSON file (details).

Output delivery

You can instead save to a path you choose (outputPath, stdio only), get an attachment for any format (asAttachment), or get a one-time download link (returnLink): see Output and file delivery.

Claude Desktop cannot display inline binary attachments (it mishandles them as images). For PDF and Office files, keep the default temp-file path, or ask for `returnLink` to get a download URL.

Tools

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

Example prompts

With your other tools. Carbone turns data that another MCP server fetches into a finished document. These assume that server (Salesforce, HubSpot, Notion, Stripe, …) is connected in the same client.

• "Get the Acme Corp opportunity and its products from Salesforce, fill my 'Sales quote' template and give me the PDF"
• "For each HubSpot deal that moved to Closed Won this week, fill the 'Service agreement' template and save the PDFs in ~/Contracts"
• "Inspect my 'Invoice' template, map its fields to the HubSpot deal 'Acme renewal', and show me the JSON before you render it"
• "Collect the tasks marked Done in the Notion 'Sprint 42' database and fill our 'Sprint report' template as a DOCX"
• "List last month's paid Stripe invoices for Acme Corp and produce an account statement with the 'Statement' template"
• "Read the attendee list from the 'Workshop' Google Sheet and create one certificate per attendee from the 'Certificate' template"
• "Summarize the pull requests merged on GitHub this week into our 'Release notes' template, then post a two-line summary in #releases on Slack"

Templates and data

• "Generate an invoice from template 1530905183164918624 with {customer: 'Acme Corp', total: 1500, items: [...]}"
• "Fill ~/templates/offer-letter.docx with ~/hr/jane-doe.json and save the PDF as ~/Documents/offer-jane-doe.pdf"
• "Show me template 1530905183164918624 as a PDF with its tags still visible, so I can check the layout"

Convert

• "Convert /Users/me/contracts/contract.docx to PDF with the Carbone ICE converter"
• "Turn https://example.com/sales.xlsx into a CSV separated by semicolons"
• "Render this PDF as a PNG thumbnail"

Batch and localization

• "Create one invoice per customer in ~/data/invoices.json, as a ZIP of files named invoice-{d.id}, delivered to my webhook https://example.com/hook"
• "Generate this invoice in French, German and Spanish from the same template"
• "Render the report with prices converted from EUR to USD at 1.08, and dates in New York time"

PDF options and template library

• "Convert this DOCX to a PDF with the open password 'secret123' and a DRAFT watermark at 20% opacity"
• "Make a PDF/A-2b copy of pages 1 to 5 of this NDA for archiving"
• "Deploy the newest version of my invoice template, and schedule the old one for deletion in 30 days"

Troubleshooting

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-mcp
curl http://localhost:3000/health

Connect your client with your key in the Authorization header:

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

In VS Code and Cursor, take the hosted server config with the URL http://localhost:3000 and add "headers": { "Authorization": "Bearer your_api_key_here" } next to "url". VS Code can prompt for the key with an inputs entry of type promptString ("Bearer ${input:carbone-api-key}"), and Cursor can read it from your environment ("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:

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

Read the shared-key warning before you use it.

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.

Security

• 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 in stdio only, where the server runs as you; over HTTP they are refused.
• Shared server key (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. This doesn't apply when no server key is set (for example on-premise Carbone without authentication).
• Browser origins (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. localhost, 127.0.0.1 and [::1] are allowed; list the browser-based clients you trust in MCP_ALLOWED_ORIGINS. Requests without an Origin (desktop, CLI and server-side clients) are unaffected.
• 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.
• 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 documents rendered with returnLink or a webhook until they are downloaded. See the privacy policy, or run Carbone on-premise for full control.

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

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.