Sign inSign up

carbone/carbone-mcp

By carbone

•Updated 28 days ago

Official MCP for Carbone — Document Generation, Document Conversion, and Universal Templating.

Image
Machine learning & AI
0

3.1K

carbone/carbone-mcp repository overview

⁠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, ChatGPT, 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
  • Pick the PDF engine per request: LibreOffice, OnlyOffice, Chromium, or Carbone ICE (converter: "I" — DOCX → PDF, up to 60x faster; note ICE ignores PDF password/permission options, use L for those)
  • Convert documents while keeping Carbone tags intact — proof a template in another format without resolving it
  • Handle localization: multi-language, currency conversion, timezone formatting

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

⁠Quick Start — HTTP Server (recommended for Docker)

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

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

⁠Docker Compose

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

CARBONE_API_KEY=your_key docker compose up -d

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

{
  "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:

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

VariableDefaultDescription
CARBONE_API_KEY—Your Carbone API key (get one free →⁠). Required for cloud API. Not required for on-premise deployments.
CARBONE_BASE_URLhttps://api.carbone.ioOverride for self-hosted Carbone instances.
CARBONE_TIMEOUT60000Request timeout in milliseconds.
CARBONE_MAX_FILE_BYTES104857600Maximum size (bytes) for a resolved input file — path, URL, or base64 (100 MB).
MCP_TRANSPORThttpTransport mode: http (default) or stdio.
MCP_PORT3000HTTP server port.
MCP_PATH/HTTP endpoint path.
MCP_MAX_BODY_BYTES62914560Maximum request body size (60 MB). Returns HTTP 413 when exceeded.
CARBONE_REQUIRE_CLIENT_AUTH_HEADERfalseRequire Authorization: Bearer <key> on every request. Left false, a request with no Bearer key falls back to the server-level CARBONE_API_KEY (a shared-key server — anyone reaching the port can spend it). Set true to require per-client keys. No effect when no server key is set.
CARBONE_ALLOW_PRIVATE_NETWORKfalseAllow user-supplied URLs to resolve to private/internal addresses. Off by default to block SSRF.

⁠On-Premise Deployment

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

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 full API reference⁠.

⁠Available Tools

ToolDescriptionDocumentation
convert_documentConvert documents between 100+ formatsConvert documents⁠
render_documentGenerate documents from templates + JSON dataGenerate documents⁠
list_templatesBrowse your template libraryList templates⁠
upload_templateStore reusable templatesUpload a template⁠
update_template_metadataRename, tag, categorize templatesPatch a template⁠
delete_templateRemove templatesDelete a template⁠
download_templateDownload original template filesDownload a template⁠
get_api_statusCheck API health and version
get_capabilitiesView supported formats and features

⁠Tags

TagDescription
latestLatest stable release
1.2.2Specific version
1.2Latest patch of 1.2
1Latest minor of v1

Supported platforms: linux/amd64, linux/arm64

⁠Links

Tag summary

Content type

Image

Digest

sha256:2f797b3db…

Size

67.3 MB

Last updated

28 days ago

docker pull carbone/carbone-mcp