carbone/carbone-mcp repository overview

⁠Carbone MCP Server

Run the official Carbone MCP server yourself: a Streamable HTTP endpoint that lets AI assistants automate production-ready PDF, Word, Excel and PowerPoint documents from templates and JSON, and convert files with 100+ conversions, through the Carbone API.

⁠Quick start

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

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

This quick start sets no server key: each MCP client sends its own Carbone key in Authorization: Bearer <key>, and only your machine can reach the port. Get a key at account.carbone.io⁠. The test key generates unlimited watermarked PDFs for free; the production key produces every format without a watermark (details⁠).

Serving 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

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

⁠What it does

• Converts DOCX, XLSX, PPTX, HTML, Markdown and PDF files to PDF, images, CSV and other formats (100+ conversions)
• Fills Word, Excel, PowerPoint, LibreOffice, HTML and Markdown templates with JSON data, and tells you which data a template expects
• Adds passwords, watermarks and PDF/A to PDFs, with a choice of converter: LibreOffice, OnlyOffice, Chromium or Carbone ICE
• Generates up to 100 documents per request, collected by the assistant (async renders) or delivered to your webhook, with translations, time zones and currency conversion
• Manages a template library: upload, version, categorize, deploy and download templates

⁠Docker Compose

services:
  carbone-mcp:
    image: carbone/carbone-mcp
    ports:
      - 127.0.0.1:3000:3000   # local only; serve other machines through a TLS reverse proxy
    restart: unless-stopped

docker compose up -d

Add any variable below under environment:. Leave CARBONE_API_KEY out so that clients send their own key: setting it gives you the shared-key variant above.

⁠Environment variables

⁠Connect your MCP client (HTTP)

Point the client at http://localhost:3000 (Streamable HTTP) with the header Authorization: Bearer <your Carbone API key>.

Claude Code:

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

VS Code (.vscode/mcp.json; VS Code 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 or .cursor/mcp.json):

{
  "mcpServers": {
    "carbone": {
      "url": "http://localhost:3000",
      "headers": { "Authorization": "Bearer your_api_key_here" }
    }
  }
}

Over HTTP, file inputs must be URLs or base64: the server cannot read the client's local files. A generated PDF or Office file comes back as a one-time download link (valid 1 hour); ask for asAttachment to get the file itself (output and file delivery⁠).

⁠Upload URLs and async renders

Both are off by default. With MCP_TICKET_SECRET and MCP_PUBLIC_URL, upload_template can return an upload URL, so an assistant that runs commands sends a large template with curl instead of base64. Add a job store and render_document accepts async: true for batches and renders over a minute: this server becomes Carbone's webhook, and get_render_result returns the download link.

Both hand out URLs on MCP_PUBLIC_URL, and Carbone calls the webhook there from the internet: run the server behind a TLS reverse proxy that serves that address and forwards to port 3000. Without it, upload URLs fail and async renders stay "still rendering".

# Once: keep this value, every restart and every instance needs the same one.
export MCP_TICKET_SECRET="$(openssl rand -base64 32)"

docker run -d --name carbone-mcp -p 127.0.0.1:3000:3000 \
  -e MCP_TICKET_SECRET \
  -e MCP_PUBLIC_URL=https://mcp.example.com \
  -e MCP_JOBS_DIR=/data/jobs -v carbone-jobs:/data/jobs \
  carbone/carbone-mcp

Here the reverse proxy on the same machine forwards https://mcp.example.com to 127.0.0.1:3000. With several instances, give them the same secret, and an S3-compatible bucket (MCP_S3_*) or a volume they all mount. Details: upload URLs⁠ and async renders⁠.

⁠Claude Desktop (stdio)

Claude Desktop starts local (stdio) servers from its config file (Settings → Developer → Edit Config):

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

In this mode, local paths and saved documents refer to the container's filesystem, which --rm deletes: pass URLs or base64 and ask for returnLink, or mount a folder with -v and use paths inside it. The npm package (npx -y carbone-mcp, Node.js 20.3+) reads and writes your own files directly.

From Claude Desktop, the stdio mode above works on every plan. A claude.ai or Claude Desktop custom connector connects from Anthropic's cloud: it can also reach this server once it is published at a public HTTPS URL (not 127.0.0.1), where your organization has Anthropic's Request headers beta, which sends the Bearer key (Anthropic docs⁠). To connect without a key, use Carbone's hosted server https://mcp.carbone.io, which signs you in with your Carbone account.

⁠On-premise Carbone

Point the server at your own Carbone instance; no API key is needed:

docker run -d -p 127.0.0.1:3000:3000 -e CARBONE_BASE_URL=https://your-carbone-server.com carbone/carbone-mcp

⁠Tools

The server exposes 12 tools (13 with async renders) to convert and render documents, inspect templates and manage a template library: see the API reference⁠.

⁠Security and troubleshooting

• URL inputs: URLs that resolve to a private or internal address (localhost, RFC 1918, cloud metadata) are refused by default. Set CARBONE_ALLOW_PRIVATE_NETWORK=true only on a trusted deployment with internal template hosts. Local paths are always refused over HTTP.
• Shared key: a server-level CARBONE_API_KEY is spent by every request that brings no key of its own, unless CARBONE_REQUIRE_CLIENT_AUTH_HEADER=true (see the shared-key variant above).
• HTTP 403 Invalid Origin: a browser-based client served from a host other than localhost. Add its hostname to MCP_ALLOWED_ORIGINS.
• HTTP 405 when you open the endpoint in a browser: expected, the endpoint only answers MCP POST requests. Check the server with GET /health.
• Prompt injection: a document or template can carry instructions aimed at the AI. Review tool calls before you confirm them.

More in the Security section of the README⁠.

⁠Tags

Supported platforms: linux/amd64, linux/arm64

⁠Links

• GitHub repository⁠
• Carbone documentation⁠
• Carbone API reference⁠
• Get an API key⁠