Carbone MCP Server

> Official Carbone MCP server — Turn AI assistants into document automation experts. Generate professional PDFs, invoices, reports, and more using natural language.

Give Claude, ChatGPT, and other AI assistants the power to:

• 🔄 Document Conversion — 100+ format combinations (PDF, DOCX, XLSX, PNG, HTML, CSV…)
• 📄 Template Engine — Generate documents from JSON data with `{d.field}` tags
• 📚 Template Library — Upload, version, categorize, and manage reusable templates
• 🎨 PDF Customization — Fill PDF forms, add watermarks, passwords, encryption, multiple converter engines (LibreOffice, OnlyOffice, Chromium, Carbone ICE)
• 🌍 Localization — Multi-language support, currency conversion, timezone handling
• ⚡ Batch Generation — Create hundreds of documents in one request (async via webhook)

Installation

Get your free API key at account.carbone.io.

stdio — Claude Desktop, VS Code, Cursor, Claude Code, and more

All stdio-compatible MCP clients use the same config:

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

> VS Code uses `{ "mcp": { "servers": { ... } } }` instead of `{ "mcpServers": { ... } }` — the inner config block is identical.

After adding the config, restart your client and try: *"What can Carbone do?"*

HTTP — mcp.carbone.io (no local installation)

Connect directly to the hosted endpoint. Supported by VS Code, Cursor, Claude Code, and other clients that support streamable HTTP transport.

{
  "mcp": {
    "servers": {
      "carbone": {
        "type": "streamable-http",
        "url": "https://mcp.carbone.io",
        "headers": {
          "Authorization": "Bearer your_api_key_here"
        }
      }
    }
  }
}

> Authentication: The HTTP endpoint currently requires a Carbone API key passed as a Bearer token in the `Authorization` header. OAuth2 support (for Claude Desktop, Mistral, ChatGPT, Gemini, and other clients) is planned for a future release.

>

> Cursor uses `{ "mcpServers": { ... } }` instead of `{ "mcp": { "servers": { ... } } }` — the inner config block is identical.

>

> Claude Desktop does not support HTTP Bearer token authentication — use the stdio option above instead.

Docker — self-hosted HTTP server

docker run -d -p 3000:3000 \
  -e MCP_TRANSPORT=http \
  -e CARBONE_API_KEY=your_api_key_here \
  carbone/carbone-mcp

Connect your MCP client to `http://your-host:3000` using the HTTP config above (replace the URL).

Docker Compose — see compose.yml:

CARBONE_API_KEY=your_key docker compose up -d

Claude Desktop with Docker (stdio) — Claude Desktop does not support HTTP transport; use the stdio mode instead:

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

On-Premise — self-hosted Carbone instance

If you run Carbone on-premise, point the MCP server at your instance — no API key required:

# Docker (HTTP)
docker run -d -p 3000:3000 \
  -e CARBONE_BASE_URL=https://your-carbone-server.com \
  carbone/carbone-mcp

# stdio
CARBONE_BASE_URL=https://your-carbone-server.com npx carbone-mcp

Environment Variables

Required (stdio mode, cloud API):

• `CARBONE_API_KEY` — Your Carbone API key (get one free →). Not required when `CARBONE_BASE_URL` points to your own on-premise server, or when running in HTTP mode (clients supply their own key via `Authorization: Bearer`).

Optional configuration

Available Tools

Document Operations

Template Management

Discovery

📖 **Full API Reference →** — Detailed parameters, schemas, and examples

Output & File Delivery

By default, a generated or converted file is returned based on its type and transport:

Three optional parameters on `convert_document` and `render_document` (and `outputPath` / `asAttachment` on `download_template`) override this:

> Claude Desktop: it cannot render inline binary attachments (it mishandles them as images). For PDFs and Office files, rely on the default stdio temp-file path, or use `returnLink` to get a download URL.

Common Use Cases

📄 Document Conversion

"Convert this Word document to PDF: /path/to/contract.docx"
"Turn my Excel spreadsheet into CSV format"
"Convert this HTML page to a PNG image"
"Convert my Markdown README to PDF"
"Convert this PPTX to PNG — use OnlyOffice for best fidelity"
"Convert this 500-page Word report to PDF — use the ICE converter, it's much faster"
"Rasterize this PDF to PNG images — one per page"

💼 Finance & Invoicing

"Generate an invoice using template T123 with: {customer: 'Acme Corp', total: 1500, items: [...]}"
"Generate invoices from the data in /data/invoices.json"
"Create 500 invoices from my billing data and bundle them in a ZIP"
"Generate a French invoice for my Paris client — use EUR currency and fr-fr locale"
"Render this monthly report for each client in clients.json and ZIP them all"
"Generate invoice-{d.id}.pdf for each row in my sales data"

⚖️ Legal & Compliance

"Add a CONFIDENTIAL watermark to this contract before sending it"
"Convert this NDA to PDF/A format for long-term archiving"
"Generate a password-protected PDF — open password: 'secret123'"
"Create signed offer letters for each candidate using this DOCX template"
"Generate a compliance report with a DRAFT watermark, 20% opacity, rotated -45°"

👥 HR & People Operations

"Create personalized onboarding documents for all 50 new employees in this JSON"
"Generate an employment contract for each person in new-hires.json"
"Build payslips for every employee in my payroll export"
"Create training certificates for everyone who passed this month"
"Fill out the performance review template with each employee's data"

🌍 Localization & Multi-Language

"Generate this invoice in French, German, and Spanish from the same template"
"Render the report with timezone America/New_York so dates show in Eastern time"
"Convert all prices from EUR to USD using today's exchange rates"
"Generate the contract in fr-fr locale so numbers use European formatting"

🔐 PDF Security & Advanced Options

"Convert this DOCX to a password-protected PDF"
"Add a semi-transparent DRAFT watermark to every page"
"Generate a PDF/A-1b compliant version of this document for archiving"
"Export only pages 1–5 of this presentation as a PDF"
"Convert each slide of this PPTX to a separate PDF page"

📚 Template Management

"Upload this invoice template and tag it 'sales' and 'finance'"
"What templates do I have in the 'contracts' category?"
"Show me all templates tagged 'hr'"
"Download template T456 so I can edit it locally"
"Deploy version V789 as the active version without deleting the others"
"Schedule this old template for deletion in 30 days"

Debugging

Using MCP Inspector

Test and debug the server interactively:

npx @modelcontextprotocol/inspector npx carbone-mcp

Or from a local build:

npx @modelcontextprotocol/inspector node dist/index.js

Open `http://localhost:5173` to view all tools, test calls, and inspect request/response JSON — no AI inference needed.

View Server Logs

# macOS — Claude Desktop logs
tail -f ~/Library/Logs/Claude/mcp*.log

# Windows
Get-Content "$env:APPDATA\Claude\logs\mcp*.log" -Wait -Tail 50

Look for:

• ✅ `Carbone MCP Server v1.x.x started (stdio)`
• ❌ Any error messages or stack traces

Health Check (HTTP mode only)

When running in HTTP mode, the server exposes a health endpoint:

curl http://localhost:3000/health

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

The `carbone` field shows backend connectivity:

• `{ "version": "..." }` — reachable and authenticated
• `{ "error": "unauthorized", "message": "..." }` — reachable but no/invalid API key
• `{ "error": "unreachable", "message": "..." }` — network error, timeout, or unexpected response

Security

⚠️ File and URL inputs (SSRF / local files)

Tools accept a local path, an HTTPS URL, or base64 for `file` / `template` and the by-reference JSON params (`data`, `complement`, …). Two guards apply:

• URLs are resolved and refused when they point at loopback, private (RFC1918), link-local (incl. cloud metadata `169.254.169.254`), CGNAT or reserved addresses — and every redirect hop is re-checked. Set `CARBONE_ALLOW_PRIVATE_NETWORK=true` only on a trusted deployment that needs internal template hosts.
• Local paths are readable in stdio only, where the server already runs as you. In HTTP mode they are refused, so a remote caller can never make the server read its own filesystem.

⚠️ Sharing a server-level API key (HTTP mode)

If you set `CARBONE_API_KEY` on an HTTP server and leave `CARBONE_REQUIRE_CLIENT_AUTH_HEADER=false` (the default), requests without a Bearer key fall back to that key — anyone who can reach the port can spend that Carbone account. Set it to `true` to require each client to bring its own key, or only expose the port on a trusted network. (Not applicable when no server key is set, e.g. on-premise Carbone without authentication.)

⚠️ Prompt Injection

Connecting an AI assistant to any external service carries inherent risks. A malicious document or template could contain instructions that trick the AI into performing unintended actions (e.g. exfiltrating data, deleting templates). Always review what your AI client is about to do before confirming tool calls.

⚠️ API Key Protection

• Never commit `CARBONE_API_KEY` to version control
• Use environment variables or a secret manager
• Rotate API keys regularly at account.carbone.io

⚠️ Template Safety

• Only upload templates from trusted sources
• Review templates before deploying them
• Use template versioning for easy rollback

⚠️ Data Privacy

• Carbone does not store your document data after rendering
• Use `CARBONE_BASE_URL` to point to a self-hosted instance for maximum control
• See Privacy Policy for details

Template Syntax

Design templates in Word, Excel, LibreOffice, or HTML with `{d.field}` tags:

Dear {d.customer.name},

Your invoice total is {d.total:formatC(EUR)}.

Items:
{d.items[i].description}  {d.items[i].quantity}x  {d.items[i].price:formatC(EUR)}
{d.items[i+1]}

Guides & best practices:

• Carbone Skill — Universal Carbone Templating syntax reference for AI tools (download .skill · GitHub)
• Template syntax
• HTML templates guide
• Markdown templates guide

Supported Output Formats

Full conversion matrix: carbone.io/documentation

Contributing

We welcome contributions:

• 🐛 Report bugs via GitHub Issues
• 💡 Request features or suggest improvements
• 📝 Improve documentation
• 🧪 Add tests to increase coverage
• 🔧 Submit pull requests with bug fixes or enhancements

See CONTRIBUTING.md for guidelines.

Development

npm run dev          # Run with tsx (no build needed)
npm run build        # Compile TypeScript → dist/
npm test             # Run the test suite (integration tests run only with CARBONE_TEST_API_KEY)
npm run test:watch   # Watch mode
npm run test:integration  # Real API tests (requires CARBONE_TEST_API_KEY)
npm run test:coverage     # Coverage report

Support

• 🤖 MCP Documentation: carbone.io/documentation/developer/ai/mcp.html
• 📚 API Documentation: carbone.io/documentation/developer/http-api/introduction.html
• 📚 Templating Documentation: carbone.io/documentation/design/overview/getting-started.html
• 🐛 Bug Reports: GitHub Issues
• 💬 Live Chat: carbone.io (bottom-right widget)
• 📧 Enterprise: contact@carbone.io
• 📋 OpenAPI specification: carbone.OpenAPI.yml

License

Apache 2.0 — see LICENSE