Carbone

Универсальный MCP для генерации и конвертации документов. Создание PDF/DOCX/XLSX из ша

Документация

Carbone MCP Server

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.

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

Setup	Runs	Clients	Files
Hosted server (recommended)	`https://mcp.carbone.io`, nothing to install	Claude, ChatGPT, Claude Code, VS Code, Cursor, …: sign in with your Carbone account	URLs, base64, ChatGPT attachments, upload URLs
Local package	`npx carbone-mcp` on your machine	Claude Desktop, Claude Code, VS Code, Cursor, and any client that starts local servers	Also reads local paths and saves documents to disk
Docker	Your own server	Clients that can send an `Authorization` header	URLs and base64

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)

Open Carbone in the Claude directory and click Connect.
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"
      }
    }
  }
}

Client	Where to put it
Claude Desktop	Settings → Developer → Edit Config opens `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/`, Windows: `%APPDATA%\Claude\`). Quit and restart Claude Desktop afterwards.
Cursor	`~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project)

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

Tool	What it does
`convert_document`	Converts a file to another format; Carbone tags stay as written
`render_document`	Fills a template with JSON data, and can convert the result (to PDF, for example)
`get_render_result`	Returns the download link of a render started with `async: true` (only when async renders are on)
`inspect_template`	Lists a template's tags and returns a matching sample dataset. Runs one render on your account (counts as one document generation)
`list_templates`	Lists stored templates, filtered by category, name or ID
`list_categories`	Lists the template categories in your account
`list_tags`	Lists the tags used across your templates
`upload_template`	Stores a reusable template, with versions, category and tags; can return an upload URL for a large file
`update_template_metadata`	Renames, categorizes, tags, deploys or schedules the deletion of a template version
`delete_template`	Deletes a template or one of its versions, immediately
`download_template`	Downloads a template's original file, or the sample data stored with it
`get_api_status`	Checks the Carbone API's health and version
`get_capabilities`	Summarizes the formats, features and usage examples

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

This server also serves the Carbone Skill itself, as skill://carbone/SKILL.md: MCP clients that support skills get it with the server, in the version matching its tools (Carbone Skill).

Troubleshooting

Symptom	Cause and fix
Carbone is connected, but a Claude chat does not use it	Turn it on for the chat: the + button, then Connectors, then Carbone.
mcp.carbone.io asks you to sign in again, or sign-in fails	Reconnect: in Claude, Disconnect then Connect the connector; in Claude Code, `/mcp` → Clear authentication, then Authenticate.
Watermark on every PDF, or only PDF works	Your account has no plan (test key): it produces watermarked PDFs only. On mcp.carbone.io, start a plan at account.carbone.io (the Free plan is enough): the server switches to your production key by itself. Locally, use the production key.
Tags such as `{d.name}` still visible in the output	`convert_document` is a pure conversion and keeps tags. Use `render_document` with your data.
A file given by name (`invoice.docx`) fails	A bare name is read as base64. Pass an absolute path (local package), a URL, or base64.
`Request body too large`, or the local connection closes	A file passed as base64 is too large (60 MB by default). Pass it by URL or local path; for a template, ask for an upload URL.
Rendering by Template ID still uses the old version after an upload	Renders by Template ID use the deployed version (most recent `deployedAt`). Ask to deploy the new version, or render by its Version ID.
Password, watermark or PDF/A missing from a PDF	PDF/A, page ranges and accessibility need the default converter `L` (LibreOffice); `O`, `C` and `I` apply passwords, permissions and watermarks only.
`Rate limit exceeded. Please wait N second(s)`	The Carbone API answered `429`. Wait the time given and try again.
Local package: `Authentication failed`, or the server stops with `CARBONE_API_KEY environment variable is required`	Set `CARBONE_API_KEY` in the client config's `env` and restart the client. Check the key at account.carbone.io.
Claude Desktop shows no Carbone tools, or the local server disconnects	Read `mcp-server-carbone.log` in `~/Library/Logs/Claude/` (macOS) or `%APPDATA%\Claude\logs\` (Windows). A good start logs `Carbone MCP Server v<version> started (stdio)`.
You want to test the server without an AI client	Run the MCP Inspector (Node.js 22.19+): `npx @modelcontextprotocol/inspector -e CARBONE_API_KEY=your_api_key_here npx carbone-mcp`.

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-mcp
curl 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

Variable	Default	Purpose
`CARBONE_API_KEY`	none	Your Carbone API key: required in stdio for Carbone Cloud, optional over HTTP (Security)
`CARBONE_BASE_URL`	`https://api.carbone.io`	Carbone API URL; set it to an on-premise instance (no key needed)
`CARBONE_TIMEOUT`	`60000`	Carbone API request timeout in ms; Carbone Cloud's own limit is 60 s
`CARBONE_MAX_FILE_BYTES`	`104857600` (100 MB)	Largest input file read from a path, URL or base64
`MCP_TRANSPORT`	`stdio` (`http` in Docker)	`stdio` or `http`
`MCP_PORT`	`3000`	HTTP port
`MCP_PATH`	`/`	HTTP endpoint path; cannot be `/health`
`MCP_MAX_BODY_BYTES`	`62914560` (60 MB)	Largest MCP message: an HTTP body (`413` above it) or a stdio message
`MCP_ALLOWED_ORIGINS`	none (localhost is always allowed)	HTTP: browser `Origin` hostnames to allow, comma-separated
`CARBONE_REQUIRE_CLIENT_AUTH_HEADER`	`false`	HTTP: `true` refuses requests that bring no Bearer key of their own
`CARBONE_ALLOW_PRIVATE_NETWORK`	`false`	`true` lets URL inputs reach private and internal addresses
`MCP_TICKET_SECRET`	none	HTTP: turns on upload URLs for large templates (details); generate with `openssl rand -base64 32`
`MCP_PUBLIC_URL`	none	HTTP, with `MCP_TICKET_SECRET`: the public `https` origin of this server, where upload URLs and Carbone's webhook point
`MCP_S3_*`	none	HTTP, with `MCP_TICKET_SECRET`: an S3-compatible bucket for async renders and batches (details)
`MCP_JOBS_DIR`	none	Instead of `MCP_S3_*`: a directory every instance shares, such as a Docker or Kubernetes volume (details)

Full descriptions: Configuration in docs/API.md.

Self-hosting troubleshooting

Symptom	Cause and fix
Tool error `Authentication failed: …`	Send `Authorization: Bearer <key>` from the client; a server with `CARBONE_REQUIRE_CLIENT_AUTH_HEADER=true` requires it on every request.
HTTP `403` `Invalid Origin: <host>`	A browser-based client served from a host other than `localhost`. Add its hostname to `MCP_ALLOWED_ORIGINS`.
HTTP `405` `Method not allowed` when you open the endpoint in a browser	Expected: the endpoint only answers MCP `POST` requests. Check the server with `GET /health`.
HTTP `413` `Request body too large`	One MCP message is over `MCP_MAX_BODY_BYTES`. Pass files by URL, or raise the limit.
`async renders: the job store cannot be read` at startup	The S3 access key needs to read, write and list the bucket, or `MCP_JOBS_DIR` must be writable.

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: contact@carbone.io

License

Apache 2.0, see LICENSE.