carbone-mcp

# Carbone MCP Server

[![npm version](https://img.shields.io/npm/v/carbone-mcp.svg)](https://www.npmjs.com/package/carbone-mcp)
[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-io.carbone%2Fcarbone--mcp-blue?logo=modelcontextprotocol)](https://registry.modelcontextprotocol.io/?q=io.carbone%2Fcarbone-mcp)
[![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

Automate production-ready PDF, Word, Excel and PowerPoint documents from templates and JSON data, and convert files between 36 formats, from Claude, Cursor, VS Code or any MCP client. The official server for the [Carbone](https://carbone.io) document generation API.

- **Convert files:** DOCX, XLSX, PPTX, HTML, Markdown or PDF to PDF, images, CSV, ODT and [the other output formats](docs/API.md#supported-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, delivered to your 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

These work on any Carbone account, even without a plan (you then get watermarked PDFs):

- *"Convert this Markdown to PDF: # Quarterly update …"*
- *"Fill my invoice template with this JSON and give me a PDF: {"customer": "Acme", "total": 1500}"*
- *"Which data does this contract template need?"* (`inspect_template` lists its tags and drafts a sample JSON)

More in [Example prompts](#example-prompts), including with Salesforce, HubSpot, Notion and Stripe.

## Quick start

> Upgrading from 1.x? Read the [upgrade notes](CHANGELOG.md#upgrading-from-1x) — HTTP deployments should upgrade now (security fixes).

### Prerequisites

- **A Carbone account** at [account.carbone.io](https://account.carbone.io). The hosted server signs you in with it and uses your production key once your account has a plan (the Free plan included), the test key until then. The local package and Docker use one of the two keys directly ([details](https://carbone.io/documentation/developer/http-api/introduction.html#requirements)):
  - **Test key**: unlimited watermarked PDFs, free (PDF output only). Templates stored with it are kept for up to 30 days.
  - **Production key**: any output format, no watermark. The Free plan includes 100 documents per month.
- **Node.js 20.3 or later** for the local package (`npx carbone-mcp`). Check with `node --version`. The Docker image needs Docker only.

### Choose a setup

| Setup | Runs | Clients | Local files |
|---|---|---|---|
| [Hosted server (HTTP)](#hosted-server-mcpcarboneio) | `https://mcp.carbone.io`, nothing to install | claude.ai, Claude Desktop, Claude Code, VS Code, Cursor, …: sign in with your Carbone account | ❌ URLs and base64 only |
| [Local package (stdio)](#local-package-stdio) | `npx carbone-mcp` on your machine | Claude Desktop, Claude Code, VS Code, Cursor, and any client that starts local servers | ✅ reads local paths, saves documents to disk |
| [Docker (HTTP)](#docker) | Your own server | Clients that can send an `Authorization` header: Claude Code, VS Code, Cursor, … | ❌ URLs and base64 only |

**claude.ai and Claude Desktop:** add the hosted server as a [connector](#claudeai-and-claude-desktop-connectors). In Claude Desktop, use the local package instead to read and save files on your computer.

### Local package (stdio)

Most clients use this config:

```json
{
  "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:**

```bash
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:

```json
{
  "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](https://modelcontextprotocol.io/docs/develop/connect-local-servers) · [Claude Code](https://code.claude.com/docs/en/mcp) · [VS Code](https://code.visualstudio.com/docs/copilot/reference/mcp-configuration) · [Cursor](https://cursor.com/docs/context/mcp)

### Hosted server (mcp.carbone.io)

Nothing to install: connect to `https://mcp.carbone.io` over Streamable HTTP, and sign in with your Carbone account when your client opens account.carbone.io in your browser. Over HTTP, file inputs must be URLs or base64 ([File inputs](#file-inputs)).

**Claude Code:** add the server, then run `/mcp`, select `carbone` and choose **Authenticate**.

```bash
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:

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

```json
{
  "mcpServers": {
    "carbone": { "url": "https://mcp.carbone.io" }
  }
}
```

### claude.ai and Claude Desktop connectors

1. Add a [custom connector](https://claude.com/docs/connectors/custom/add-unlisted) with the URL `https://mcp.carbone.io`. Leave the OAuth client ID and secret empty.
2. Click **Connect**, sign in with your Carbone account and approve.

In an organization, each member connects with their own Carbone account, and their documents count against it. Claude Desktop uses the same connectors; to read and save files on your computer, use the [local package](#local-package-stdio) instead.

## Files in and out

### File inputs

`file` (`convert_document`) and `template` (`render_document`, `inspect_template`, `upload_template`) accept:

| Form | Example | stdio | HTTP |
|---|---|---|---|
| Absolute local path | `/Users/me/invoice.docx`, `~/invoice.docx`, `C:\Users\me\invoice.docx` | ✅ | ❌ refused |
| URL | `https://example.com/invoice.docx` | ✅ | ✅ |
| Base64 | the file content, base64-encoded | ✅ | ✅ |

Any other string, such as a bare `invoice.docx`, is read as base64 and fails. Relative paths (`./…`, `../…`) resolve against the server's working directory, which your client chooses: prefer absolute paths. The JSON parameters (`data`, `complement`, …) also accept a path, URL or base64 string pointing to a JSON file ([details](docs/API.md#pass-json-by-reference)).

### Output delivery

| Output | stdio (local clients) | HTTP (remote / self-hosted) |
|---|---|---|
| Text: HTML, TXT, CSV, MD, XML, JSON (template samples) | inline text | inline text |
| Images: PNG, JPG, GIF, WEBP | inline image | inline image |
| Everything else: PDF, Office, SVG, TIFF… | saved to a temp file, path returned | returned as a download attachment |

You can instead save to a path you choose (`outputPath`, stdio only), get an attachment for any format (`asAttachment`), or get a one-time download link (`returnLink`): see [Output and file delivery](docs/API.md#output--file-delivery).

> **Claude Desktop** cannot display inline binary attachments (it mishandles them as images). For PDF and Office files, keep the default temp-file path, or ask for **`returnLink`** to get a download URL.

## 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) |
| `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 |
| `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](docs/API.md).

## Example prompts

**With your other tools.** Carbone turns data that another MCP server fetches into a finished document. These assume that server (Salesforce, HubSpot, Notion, Stripe, …) is connected in the same client.
- *"Get the Acme Corp opportunity and its products from Salesforce, fill my 'Sales quote' template and give me the PDF"*
- *"For each HubSpot deal that moved to Closed Won this week, fill the 'Service agreement' template and save the PDFs in ~/Contracts"*
- *"Inspect my 'Invoice' template, map its fields to the HubSpot deal 'Acme ren