io.carbone/carbone-mcp

Official11 tools

by carboneio · TypeScript

Carbone MCP

Generate PDF/DOCX/XLSX/PPTX from templates+JSON. Convert Office/HTML/MD to PDF. Universal templating

Generate and convert documents between PDF, DOCX, XLSX, PPTX formats from templates.

Topics

csvdocument-conversiondocument-generationdocxhtmlmarkdownmcpmcp-serverpdfpdf-generationpptxtemplate-enginexlsx

Captured live from the server via tools/list.

list_templates

List stored Carbone templates with filtering, search, and pagination. Filter by Template ID, Version ID, category, or upload origin. Use includeVersions to see the full version history of each template. Supports cursor-based pagination for large collections. Note: filtering by tags is not supported by the Carbone API — use list_tags to discover tags, then filter results manually. Note: templates uploaded with versioning disabled appear with id = null and are identified only by their versionId — pass that versionId where a Template ID is expected (e.g. delete_template, download_template).

Parameters (8)

idstring
Filter by Template ID (64-bit format). Cannot be a Version ID.
versionIdstring
Filter by Version ID (SHA-256 format).
categorystring
Filter by category (e.g. "invoices", "legal").
origininteger
Filter by upload origin. 0 = uploaded via API, 1 = uploaded via Carbone Studio.
includeVersionsboolean
If true, returns all versions for each template. Default: false (only deployed version).
searchstring
Fuzzy search in template names, or exact match on Template ID / Version ID.
limitinteger
Maximum number of results to return. Must be between 1 and 100 (Carbone API limit). Default: 100.
cursorstring
Pagination cursor from the previous response nextCursor field. Use to fetch the next page.

convert_document

Convert any document to another format without storing a template. Supports 100+ input/output format combinations: Office documents, PDFs, images, web pages, spreadsheets, and more. The source file can be a local path, a URL, or a base64 string. Use render_document instead when you need data injection ({d.field} tags), translations, or batch generation. Common conversions: DOCX → PDF (file: "report.docx", convertTo: "pdf"), XLSX → PDF (file: "data.xlsx", convertTo: "pdf"), PPTX → PDF (file: "slides.pptx", convertTo: "pdf", converter: "O" for best fidelity), HTML → PDF (file: "page.html", convertTo: "pdf", converter: "C" for full CSS/JS rendering), DOCX → HTML (file: "doc.docx", convertTo: "html"), XLSX → CSV (file: "sheet.xlsx", convertTo: "csv"), PDF → PNG (file: "doc.pdf", convertTo: "png"), PPTX → PNG (first slide as image), MD → PDF (file: "readme.md", convertTo: "pdf").

Parameters (7)

filestringrequired
The document to convert. Three input forms are accepted: (1) Local file path — absolute or relative, e.g. "/home/user/report.docx" or "./invoice.xlsx". (2) HTTPS URL — the file is downloaded automatically, e.g. "https://example.com/file.pptx". (3) Base64-encoded string — the raw file content encoded as base64. Supported input formats include: DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, HTML, XHTML, XML, IDML, Markdown (MD), PDF, TXT, CSV, PNG, JPG, SVG, and more. Full conversion matrix: https://carbone.io/documentation/developer/http-api/generate-reports.md
convertToanyrequired
Target output format. Documents : "pdf", "docx", "xlsx", "pptx", "odt", "ods", "odp", "odg", "rtf", "epub". Web/text : "html", "xhtml", "txt", "csv", "md", "xml", "idml". Images : "png", "jpg", "jpeg", "webp", "svg", "tiff", "bmp", "gif". Archive : "zip" (batch output). Simple usage: "pdf". Advanced usage: { "formatName": "pdf", "formatOptions": { "EncryptFile": true, "DocumentOpenPassword": "secret" } }.
converterstring
Converter engine. Only relevant when convertTo is "pdf" (or an image format rasterised from a document). "L" — LibreOffice (default): best all-round engine for DOCX, XLSX, PPTX, ODT, ODS, ODP. "O" — OnlyOffice: highest fidelity rendering for Microsoft Office formats (DOCX, XLSX, PPTX). "C" — Chromium: best for HTML, CSS, JavaScript — full browser rendering. If omitted, LibreOffice is used by default.
outputPathstring
Optional local file path to save the converted document to (e.g. "/home/user/out.pdf" or "~/out.pdf"). When set, the file is written to disk and the tool returns the saved path + size instead of embedding the document inline — ideal for large files. Local (stdio) mode only; rejected in HTTP mode.
asAttachmentboolean
If true, return the document as a downloadable file attachment (a base64 EmbeddedResource), for any format. Default delivery: text and png/jpg/gif/webp are returned inline; other binary outputs (PDF, Office, …) are saved to a temp file in stdio mode (path returned), or returned as an attachment in HTTP mode. Ignored when outputPath or returnLink is set.
returnLinkboolean
If true, generate the document and return a public download URL instead of the file contents. The link is SHORT-LIVED and ONE-TIME — Carbone deletes the file after the first download — so it is meant for the end user to download once (do not fetch it programmatically). Works in stdio and HTTP. Mutually exclusive with outputPath and asAttachment.
egressAuthorizationstring
Value for the Authorization header Carbone adds to its OUTBOUND (egress) requests during conversion — e.g. when a Chromium HTML→PDF conversion fetches a protected external image or stylesheet. For example "Bearer abc123" makes Carbone send `authorization: Bearer abc123` to those hosts. Only the authorization header can be customised; max 512 characters.

render_document

Generate a document by merging a Carbone template with JSON data. Two modes: (1) pass templateId to use a previously uploaded template; (2) pass template (file path, URL, or base64) to upload and render in a single request without storing a template. Supports output format conversion, multilingual rendering, currency conversion, batch generation, and advanced PDF options (watermark, password, PDF/A). Async mode: pass webhookUrl to render asynchronously — Carbone will POST the renderId to your URL when the document is ready. Async mode is required when using batch generation (batchSplitBy).

Parameters (25)

templateIdstring
The ID of a previously uploaded template to render. Two ID formats are accepted: (1) Template ID (64-bit) — stable identifier shared across versions; Carbone automatically uses the deployed version. (2) Version ID (SHA-256) — pins rendering to a specific version regardless of deployment status. Both are returned by upload_template. Mutually exclusive with template — provide exactly one, never both.
templatestring
Inline template for one-shot render without storing a template first. Accepts a local file path (e.g. /home/user/invoice.docx), a URL (https://example.com/template.docx), or a base64-encoded string. The template is uploaded and rendered in a single API request — no Template ID is returned. Use this for ephemeral renders; use upload_template + templateId when you need to reuse the template. Supported formats: DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, HTML, XHTML, IDML, XML, Markdown (MD), PDF, and more. Mutually exclusive with templateId — provide exactly one, never both.
dataany
JSON data merged into the template — an object, or a top-level array (accessed with {d[i].field}). Access fields with {d.fieldName} tags. Nested objects: {d.customer.name}. Array loops: {d.items[i].description} … {d.items[i+1]}. Conditionals: {d.status == "active" ? "Yes" : "No"}. Optional — if omitted, defaults to an empty object {} so the template is simply converted (tags resolve to empty). Useful to convert a stored template by templateId without data injection. Instead of inlining a large dataset, you may pass a STRING reference to the JSON: a local file path (e.g. "/data/invoices.json"), an HTTPS URL, or a base64-encoded JSON string — it is read and parsed server-side. Local paths resolve in stdio (local) mode only; URLs and base64 work in both transports.
convertToany
Output format. If omitted, the output matches the template format. Documents : "pdf", "docx", "xlsx", "pptx", "odt", "ods", "odp", "odg", "rtf", "epub". Web/text : "html", "xhtml", "txt", "csv", "md", "xml", "idml". Images : "png", "jpg", "jpeg", "webp", "svg", "tiff", "bmp", "gif". Archive : "zip" (use with batchSplitBy for batch output). Simple usage: "pdf". Advanced usage: { "formatName": "pdf", "formatOptions": { ... } } for PDF-specific options.
converterstring
Converter engine. Only relevant when convertTo is "pdf" (or an image rasterised from a document). "L" — LibreOffice (default): best all-round engine for DOCX, XLSX, PPTX, ODT, ODS, ODP. "O" — OnlyOffice: highest fidelity for Microsoft Office formats (DOCX, XLSX, PPTX). "C" — Chromium: best for HTML/CSS/JS templates — full browser rendering. If omitted, LibreOffice is used by default.
timezonestring
IANA timezone used to convert dates in the rendered document. Default: "Europe/Paris". Applied when templates use the :formatD formatter, e.g. {d.date:formatD(YYYY-MM-DD HH:mm)}. Common values: "UTC", "America/New_York", "America/Los_Angeles", "Europe/London", "Europe/Paris", "Europe/Berlin", "Asia/Tokyo", "Asia/Shanghai", "Australia/Sydney". Full list (TZ identifier column): https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
langstring
Locale of the generated document. Affects three things: (1) {t(key)} translation tags — selects the matching translation from the translations map. (2) :formatN number formatter — applies locale-specific thousand/decimal separators. (3) :formatC currency formatter — applies locale-specific currency symbols and formatting. Format: BCP-47 lowercase, e.g. "fr-fr", "en-us", "de-de", "es-es", "pt-br", "zh-cn", "ja-jp". Full list: https://github.com/carboneio/carbone/blob/master/formatters/_locale.js
complementany
Extra data object accessible in templates with {c.field} tags (as opposed to {d.field} for main data). Useful for static or shared values that should not be mixed into the main dataset: company info, logo URLs, footer text, configuration constants. Example: { "company": "Acme Corp", "address": "123 Main St", "vatNumber": "FR12345" }. Like data, may instead be passed by reference as a string — a local path, HTTPS URL, or base64 to a JSON file.
variableStrstring
Carbone alias expressions evaluated once before rendering, available everywhere in the template. Used to pre-compute reusable values or shorten repetitive paths. Syntax: "{#aliasName = expression}". Example: "{#fullName = d.firstName + \" \" + d.lastName}{#total = d.price * d.qty}". Aliases are then used in the template as {#fullName}, {#total}. Documentation: https://carbone.io/documentation.html#alias
reportNamestring
Filename (WITHOUT extension) for the generated document, returned in the Content-Disposition header. Carbone automatically appends the extension that matches convertTo, so do not include one — passing "invoice.pdf" yields "invoice.pdf.pdf". Supports Carbone tags resolved against the data at render time. Examples: "invoice" (static), "{d.type}-{d.id}" (dynamic), "{d.client}-{d.date:formatD(YYYY-MM)}".
enumany
Enumeration map used with the :convEnum(TYPE) formatter to translate code values into human-readable labels. Define one key per enum type; each value is an object mapping code → label. Example: { "STATUS": { "1": "Active", "2": "Inactive", "3": "Pending" }, "ROLE": { "A": "Admin", "U": "User" } }. Template usage: {d.status:convEnum(STATUS)}, {d.role:convEnum(ROLE)}. May instead be passed by reference as a string — a local path, HTTPS URL, or base64 to a JSON file. Documentation: https://carbone.io/documentation.html#convenum-type-
translationsany
Translation map for multilingual documents. Requires "lang" to be set to select the active locale. Top-level keys are BCP-47 locale codes; values are key → translated-string maps. Template usage: {t(greeting)} is replaced by the matching string for the active locale. Example: { "fr-fr": { "greeting": "Bonjour", "total": "Total" }, "en-us": { "greeting": "Hello", "total": "Total" } }. These dictionaries get large, so you may instead pass a string reference — a local path, HTTPS URL, or base64 to a JSON file. Documentation: https://carbone.io/documentation.html#translations
currencySourcestring
ISO 4217 currency code of the monetary amounts in the JSON data. Used by the :formatC formatter as the conversion source. Must be set together with currencyTarget and currencyRates. Example: "EUR" if all prices in your data are in euros.
currencyTargetstring
ISO 4217 currency code of the output document. The :formatC formatter converts amounts from currencySource to this currency using currencyRates. Must be set together with currencySource and currencyRates. Example: "USD" to display prices in US dollars. Documentation: https://carbone.io/documentation.html#formatc-precisionorformat-
currencyRatesany
Exchange rate table used by :formatC for currency conversion. Keys are ISO 4217 currency codes; values are rates relative to a common base. The base currency should have rate 1. Example: { "EUR": 1, "USD": 1.08, "GBP": 0.86, "JPY": 160.5 }. May instead be passed by reference as a string — a local path, HTTPS URL, or base64 to a JSON file.
hardRefreshboolean
If true, Carbone recomputes pagination and refreshes the table of contents after rendering. Requires convertTo to be defined. Use this for DOCX/ODT templates that contain a TOC field or cross-references that need updating after data injection.
batchSplitBystring
JSON path to the array in your data that drives batch generation. One document is generated per element of the array; all documents are bundled together. Use batchOutput: "zip" to receive a single ZIP archive. Use batchReportName to customise each filename inside the ZIP. Example: "d.invoices" — produces one PDF per item in data.invoices. Example: "d.employees" — produces one contract per employee.
batchOutputstring
Container format for the batch result. Use "zip" to receive all generated documents as a single ZIP archive. Must be used together with batchSplitBy.
batchReportNamestring
Filename pattern for each individual document inside the batch ZIP. Supports Carbone tags. Tags are resolved against the item's data (relative path) or the full dataset (absolute path). Examples: "invoice-{d.id}.pdf", "{d.client.name}-{d.date}.docx". Must be used together with batchSplitBy.
webhookUrlstring
Webhook URL to enable asynchronous rendering. When provided, Carbone returns immediately and POSTs { "success": true, "data": { "renderId": "..." } } to this URL when the document is ready. The default render timeout is extended to 5 minutes on Carbone Cloud (vs 60 s for synchronous requests). Download the document with GET /render/:renderId once the webhook is received. Required when using batchSplitBy (batch generation is always asynchronous). Example: "https://your-server.com/carbone-webhook".
webhookHeadersobject
Custom headers Carbone will include when POSTing to your webhookUrl. Pass plain header names as keys — the prefix "carbone-webhook-header-" is added automatically before sending to Carbone, and Carbone forwards the original header names to your webhook endpoint. Example: { "authorization": "my-secret", "custom-id": "12345", "custom-name": "Jane Doe" } — Carbone will call your URL with headers: authorization: my-secret, custom-id: 12345, custom-name: Jane Doe. Requires webhookUrl to be set.
egressAuthorizationstring
Value for the Authorization header Carbone adds to its OUTBOUND (egress) requests while rendering — fetching external images ({d.imageUrl}), external PDFs (:appendFile / :attachFile), and calling webhooks. For example "Bearer abc123" or "my-secret" makes Carbone send `authorization: <value>` to those hosts. Only the authorization header can be customised; max 512 characters. For webhook calls specifically, webhookHeaders.authorization (if set) overrides this value.
outputPathstring
Optional local file path to save the generated document to (e.g. "/home/user/out.pdf" or "~/out.pdf"). When set, the file is written to disk and the tool returns the saved path + size instead of embedding the document inline — ideal for large files. Local (stdio) mode only; rejected in HTTP mode. Ignored for async/webhook renders (no document is returned inline).
asAttachmentboolean
If true, return the document as a downloadable file attachment (a base64 EmbeddedResource), for any format. Default delivery: text and png/jpg/gif/webp are returned inline; other binary outputs (PDF, Office, …) are saved to a temp file in stdio mode (path returned), or returned as an attachment in HTTP mode. Ignored when outputPath or returnLink is set.
returnLinkboolean
If true, generate the document and return a public download URL instead of the file contents. The link is SHORT-LIVED and ONE-TIME — Carbone deletes the file after the first download — so it is meant for the end user to download once (do not fetch it programmatically). Works in stdio and HTTP. Mutually exclusive with outputPath, asAttachment, and webhookUrl (async).

list_categories

List all template categories currently in use in your Carbone account. Categories act like folders for organising templates (e.g. "invoices", "legal", "hr"). Use the returned names as the category filter in list_templates or upload_template.

No parameters.

list_tags

List all tags currently used across templates in your Carbone account. Tags are free-form labels attached to templates (e.g. "sales", "billing", "v2"). Note: the Carbone API does not support filtering list_templates by tag — use this tool to discover available tags, then call list_templates and filter the results manually.

No parameters.

upload_template

Upload and store a reusable Carbone template. Once uploaded, use render_document with the returned Template ID to generate documents from it. Supports versioning: multiple versions can live under a single stable Template ID, with deployedAt controlling which version is active. Accepted formats: DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, HTML, XHTML, IDML, XML, Markdown, PDF, and more.

Parameters (10)

templatestringrequired
The template file. Accepts a local file path (e.g. /home/user/invoice.docx), a URL (https://example.com/template.docx), or a base64-encoded string. Supported formats: DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, HTML, XHTML, IDML, XML, Markdown (MD), PDF, and more. Full list: https://carbone.io/documentation/developer/http-api/generate-reports.md
namestringrequired
Display name for the template (e.g. "Invoice Template", "NDA Contract").
idstring
Existing Template ID (64-bit format) to add this upload to its version history. If omitted, a new Template ID is generated. Providing a Version ID (SHA-256) is not allowed and will cause an error.
versioningboolean
Enable template versioning (default: true). When true, a stable Template ID is generated and multiple versions can be managed under it. When false, behaves as legacy mode and returns only a templateId (SHA-256 hash).
categorystring
Group templates into folders/categories (e.g. "invoices", "legal", "hr").
commentstring
Free-text comment to describe the template version or its purpose.
tagsarray
Tags for searchability and filtering (e.g. ["sales", "billing", "v2"]).
samplearray
Sample input data attached to the template for testing in Carbone Studio. Each item must include data, complement, translations, and enum objects.
deployedAtinteger
UTC Unix timestamp (seconds) to set as the deployment time for this version. Carbone uses the version with the most recent deployedAt when rendering via Template ID. Use 42000000000 to deploy immediately (special "NOW" sentinel value).
expireAtinteger
UTC Unix timestamp (seconds) at which this template will be automatically deleted. Use 42000000000 to delete immediately (special "NOW" sentinel value).

update_template_metadata

Update the metadata of a stored template: name, comment, category, tags, deployment timestamp, or expiration. Use deployedAt to activate a specific version for rendering. Use expireAt to schedule or trigger immediate deletion.

Parameters (7)

templateIdstringrequired
Template ID (64-bit) or Version ID (SHA-256) to update. Using a Template ID updates the metadata shared by all versions. Using a Version ID updates only that specific version.
namestring
New display name.
commentstring
New free-text comment.
categorystring
New category.
tagsarray
New list of tags — replaces existing tags entirely.
deployedAtinteger
Unix timestamp (seconds) to set as the deployment time for this version. Carbone picks the version with the most recent deployedAt when rendering. Use 42000000000 to deploy immediately (special "NOW" value).
expireAtinteger
Unix timestamp (seconds) at which this template will be automatically deleted. Use 42000000000 to delete immediately.

delete_template

Delete a stored Carbone template. This is a soft delete: the template is marked for garbage collection and removed after a delay (default 24 hours). You can delete by Template ID (removes all versions) or by Version ID (removes only that specific version). For immediate or scheduled deletion, use update_template_metadata with expireAt = 42000000000 (NOW) or a future Unix timestamp.

Parameters (1)

templateIdstringrequired
Template ID (64-bit) or Version ID (SHA-256) to delete. Template ID — deletes the template record and all its versions. Version ID — deletes only that specific version, leaving other versions intact. Both formats are returned by upload_template and list_templates.

download_template

Download the original source file of a stored Carbone template (e.g. the DOCX, XLSX, PPTX, or HTML file that was uploaded). Use this to inspect, edit, or back up a template. Pass a Template ID to download the currently deployed version, or a Version ID to download a specific version.

Parameters (3)

templateIdstringrequired
Template ID (64-bit) or Version ID (SHA-256) to download. Template ID — downloads the currently deployed version of the template. Version ID — downloads that exact version regardless of deployment status. Both formats are returned by upload_template and list_templates.
outputPathstring
Optional local file path to save the template file to (e.g. "/home/user/template.docx" or "~/template.docx"). When set, the file is written to disk and the tool returns the saved path + size instead of embedding the file inline. Local (stdio) mode only; rejected in HTTP mode.
asAttachmentboolean
If true, return the template as a downloadable file attachment (base64 resource) instead of inline text/image. Useful in HTTP mode where outputPath is unavailable. Default: false. Ignored when outputPath is set.

get_api_status

Check Carbone API health and version. Returns the current API version and a status message. Useful for verifying connectivity and confirming which Carbone version is active.

No parameters.

get_capabilities

Returns a summary of all Carbone capabilities: supported formats, features, tool usage examples, and links to full documentation. Call this first if you are unsure what Carbone can do.

No parameters.

README.md17 KBView on GitHub

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
🌍 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:

json

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

Client	Config file
Claude Desktop (macOS)	`~/Library/Application Support/Claude/claude_desktop_config.json`
Claude Desktop (Windows)	`%APPDATA%\Claude\claude_desktop_config.json`
Cursor (global)	`~/.cursor/mcp.json`
Cursor (project)	`.cursor/mcp.json`
Claude Code	`claude mcp add carbone-mcp -e CARBONE_API_KEY=your_key -- npx -y carbone-mcp`

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.

json

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

bash

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:

bash

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:

json

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

bash

# 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).

<details> <summary>Optional configuration</summary>

Variable	Default	Description
`CARBONE_BASE_URL`	`https://api.carbone.io`	Override for self-hosted or staging environments. When set to a custom URL, `CARBONE_API_KEY` is not required.
`CARBONE_TIMEOUT`	`60000`	Request timeout in milliseconds (max: 60000)
`CARBONE_MAX_FILE_BYTES`	`104857600`	Maximum size (bytes) for a resolved input file — path, URL, or base64 (100 MB default)
`MCP_TRANSPORT`	`stdio`	Transport mode: `stdio` (default, for AI clients) or `http` (for self-hosted deployments)
`MCP_PORT`	`3000`	HTTP server port (only used when `MCP_TRANSPORT=http`)
`MCP_PATH`	`/`	HTTP endpoint path (only used when `MCP_TRANSPORT=http`)
`MCP_MAX_BODY_BYTES`	`62914560`	Maximum request body size in bytes (60 MB default, matching Carbone Cloud limit)
`CARBONE_REQUIRE_CLIENT_AUTH_HEADER`	`false`	HTTP mode only — reject requests without a Bearer key instead of falling back to the server-level `CARBONE_API_KEY` (multi-tenant safety)

</details>

Available Tools

Document Operations

Tool	Description	Docs
`convert_document`	Convert documents between 100+ formats without storing a template	→
`render_document`	Generate documents from templates by merging with JSON data	→

Template Management

Tool	Description	Docs
`list_templates`	Browse your template library with filtering by category or search (tags are returned per template but not filterable server-side)	→
`list_categories`	List all template categories in your account	→
`list_tags`	List all tags used across your templates	→
`upload_template`	Store reusable templates with versioning, categorization, and metadata	→
`update_template_metadata`	Rename, categorize, tag, deploy, or expire template versions	→
`delete_template`	Soft-delete templates (marked for removal, gone after ~24h)	→
`download_template`	Download original template files (DOCX, XLSX, PDF, etc.)	→

Discovery

Tool	Description	Docs
`get_api_status`	Check Carbone API health and current version
`get_capabilities`	View all supported formats, features, and examples

📖 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:

Output	stdio (local clients)	HTTP (remote / self-hosted)
Text — HTML, TXT, CSV, MD, XML	inline text	inline text
Inline images — PNG, JPG, GIF, WEBP	inline image	inline image
Everything else — PDF, Office, ZIP, SVG…	saved to a temp file, path returned	returned as a download attachment

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

Parameter	Effect
`outputPath`	stdio only — save the output to this local path instead of returning it inline (rejected in HTTP mode)
`asAttachment`	return the bytes as a downloadable attachment for any format, instead of inline
`returnLink`	return Carbone's public one-time download URL instead of the file — short-lived and consumed by the first download, so hand it to the user rather than fetching it yourself (works in stdio and HTTP)

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

code

"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"
"Rasterize this PDF to PNG images — one per page"

💼 Finance & Invoicing

code

"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

code

"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

code

"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

code

"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

code

"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

code

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

bash

npx @modelcontextprotocol/inspector npx carbone-mcp

Or from a local build:

bash

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

bash

# 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:

bash

curl http://localhost:3000/health

json

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

⚠️ 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:

code

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

Category	Formats
Documents	PDF, DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, RTF, EPUB
Images	PNG, JPG, WEBP, SVG, TIFF, BMP, GIF
Web / Text	HTML, TXT, CSV, MD, XML

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

bash

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

Install

Configuration

Environment variables

CARBONE_API_KEYrequiredsecret

Your Carbone API key from https://account.carbone.io. Required when using the Carbone cloud API. If CARBONE_BASE_URL points to an on-premise server, authentication is not required and this can be left empty.

CARBONE_BASE_URLdefault https://api.carbone.io

Custom Carbone API base URL for on-premise deployments. Defaults to https://api.carbone.io. When set to a custom URL, CARBONE_API_KEY is not required.

claude_desktop_config.json

{
  "mcpServers": {
    "carbone-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "carbone-mcp@1.4.0"
      ],
      "env": {
        "CARBONE_API_KEY": "<YOUR_CARBONE_API_KEY>",
        "CARBONE_BASE_URL": "https://api.carbone.io"
      }
    }
  }
}