carbone/carbone-mcp

Carbone MCP Server

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

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

• Convert between 100+ document formats instantly (Office, HTML, Markdown → PDF, PNG, CSV…)
• Generate PDF, DOCX, XLSX, PPTX from templates and JSON data using {d.field} tags
• Manage template libraries with versioning, categorization, and metadata
• Fill PDF forms programmatically
• Create batch documents — invoices, certificates, contracts, payslips — in one request
• Add watermarks, passwords, encryption, and PDF/A compliance
• Handle localization: multi-language, currency conversion, timezone formatting

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

---

Quick Start — HTTP Server (recommended for Docker)

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

Connect your MCP client to http://your-host:3000 with Authorization: Bearer your_api_key_here.

Health check

bash
curl http://localhost:3000/health

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

---

Docker Compose

yaml
services:
  carbone-mcp:
    image: carbone/carbone-mcp
    ports:
      - 3000:3000
    environment:
      - CARBONE_API_KEY=${CARBONE_API_KEY}
      - MCP_PORT=3000
    restart: unless-stopped

bash
CARBONE_API_KEY=your_key docker compose up -d

---

Connect to VS Code / Cursor / Claude Code (HTTP)

json
{
  "mcp": {
    "servers": {
      "carbone": {
        "type": "streamable-http",
        "url": "http://your-host:3000",
        "headers": {
          "Authorization": "Bearer your_api_key_here"
        }
      }
    }
  }
}

---

Connect to Claude Desktop (stdio)

Claude Desktop does not support HTTP Bearer token authentication. Use stdio transport instead:

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

---

Environment Variables

---

On-Premise Deployment

Point to your own Carbone server — no API key required:

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

---

Output & file delivery

In HTTP mode (the Docker default), a generated PDF / Office / ZIP file is returned as a download attachment (an MCP EmbeddedResource); text and PNG/JPG/GIF/WEBP come back inline. Two options on convert_document / render_document change this:

• asAttachment — force a download attachment for any format
• returnLink — return Carbone's public one-time download URL instead of the bytes (hand it to the user; it is consumed by the first download)

outputPath (save to a local file) is stdio-only — in HTTP mode the file would land inside the container, so it is rejected. See the https://github.com/carboneio/carbone-mcp/blob/master/docs/API.md#output--file-delivery.

---

Available Tools

---

Tags

Supported platforms: linux/amd64, linux/arm64

---

Links

• https://github.com/carboneio/carbone-mcp
• Full Documentation
• Carbone API Reference
• Get API Key