Summary
Connects Claude to Carbone's document generation and conversion API. Exposes tools to convert between 100+ formats (PDF, DOCX, XLSX, HTML, Markdown, images), render documents from templates using JSON data injection, and manage a template library with versioning and categories. Includes batch generation, PDF watermarking, form filling, and localization support. Works via stdio (Claude Desktop, Cursor, VS Code) or streamable HTTP at mcp.carbone.io. Requires a Carbone API key for the cloud service, or point it at your own on-premise instance. Useful when you need Claude to produce finished documents, invoices, or reports rather than just draft text.
Install to Claude Code
verifiedclaude mcp add --transport http carbone-mcp https://mcp.carbone.ioRun in your terminal. Add --scope user to make it available in every project.
Review the command, arguments, and environment values before installing — MCP servers run with your local permissions.
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →
Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →
Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →
On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →
Tools
Verified live against the running server on Jun 10, 2026.
verified live11 tools
list_templatesList 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...8 params
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...
Parameters* required
idstringFilter by Template ID (64-bit format). Cannot be a Version ID.
limitintegerMaximum number of results to return (default: 100).
cursorstringPagination cursor from the previous response nextCursor field. Use to fetch the next page.
originintegerFilter by upload origin. 0 = uploaded via API, 1 = uploaded via Carbone Studio.
searchstringFuzzy search in template names, or exact match on Template ID / Version ID.
categorystringFilter by category (e.g. "invoices", "legal").
versionIdstringFilter by Version ID (SHA-256 format).
includeVersionsbooleanIf true, returns all versions for each template. Default: false (only deployed version).
convert_documentConvert 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 whe...3 params
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 whe...
Parameters* required
file*stringThe 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.html#output-file-type
convertTo*valueTarget 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" } }.
converterstringConverter 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.one of
L · C · Orender_documentGenerate 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 con...21 params
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 con...
Parameters* required
data*objectJSON data merged into the template. 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"}. For pure document conversion without data injection, pass {}.
enumobjectEnumeration 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)}. Documentation: https://carbone.io/documentation.html#convenum-type-
langstringLocale 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
templatestringInline 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.
timezonestringIANA 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
convertTovalueOutput 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.
converterstringConverter 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.one of
L · C · OcomplementobjectExtra 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" }
reportNamestringFilename for the generated document, returned in the Content-Disposition header. Supports Carbone tags resolved against the data at render time. Examples: "invoice.pdf" (static), "{d.type}-{d.id}.pdf" (dynamic), "{d.client}-{d.date:formatD(YYYY-MM)}.docx".
templateIdstringThe 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.
webhookUrlstringWebhook 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".
batchOutputstringContainer format for the batch result. Use "zip" to receive all generated documents as a single ZIP archive. Must be used together with batchSplitBy.
hardRefreshbooleanIf 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.
variableStrstringCarbone 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
batchSplitBystringJSON 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.
translationsobjectTranslation 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" } }. Documentation: https://carbone.io/documentation.html#translations
currencyRatesobjectExchange 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 }.
currencySourcestringISO 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.
currencyTargetstringISO 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-
webhookHeadersobjectCustom 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.
batchReportNamestringFilename 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.
list_categoriesList 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.
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 — call it with no arguments.
list_tagsList 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 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...
No parameters — call it with no arguments.
upload_templateUpload 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....10 params
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....
Parameters* required
idstringExisting 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.
name*stringDisplay name for the template (e.g. "Invoice Template", "NDA Contract").
tagsarrayTags for searchability and filtering (e.g. ["sales", "billing", "v2"]).
samplearraySample input data attached to the template for testing in Carbone Studio. Each item must include data, complement, translations, and enum objects.
commentstringFree-text comment to describe the template version or its purpose.
categorystringGroup templates into folders/categories (e.g. "invoices", "legal", "hr").
expireAtintegerUTC Unix timestamp (seconds) at which this template will be automatically deleted. Use 42000000000 to delete immediately (special "NOW" sentinel value).
template*stringThe 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.html#output-file-type
deployedAtintegerUTC 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).
versioningbooleanEnable 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).default: true
update_template_metadataUpdate 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.7 params
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* required
namestringNew display name.
tagsarrayNew list of tags — replaces existing tags entirely.
commentstringNew free-text comment.
categorystringNew category.
expireAtintegerUnix timestamp (seconds) at which this template will be automatically deleted. Use 42000000000 to delete immediately.
deployedAtintegerUnix 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).
templateId*stringTemplate 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.
delete_templateDelete 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 sch...1 params
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 sch...
Parameters* required
templateId*stringTemplate 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_templateDownload 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 v...1 params
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 v...
Parameters* required
templateId*stringTemplate 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.
get_api_statusCheck 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.
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 — call it with no arguments.
get_capabilitiesReturns 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.
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 — call it with no arguments.
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:
{
"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.
{
"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
Authorizationheader. 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 whenCARBONE_BASE_URLpoints to your own on-premise server, or when running in HTTP mode (clients supply their own key viaAuthorization: Bearer).
Optional configuration
| 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) |
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
returnLinkto 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"
"Rasterize this PDF to PNG images — one per page"
💼 Finance & Invoicing
"Generate an invoice using template T123 with: {customer: 'Acme Corp', total: 1500, items: [...]}"
"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
⚠️ 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_KEYto 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_URLto 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
| 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
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
Featured
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →Configuration
CARBONE_API_KEY*secretYour 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.ioCustom 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.
Registryactive
Packagecarbone-mcp
TransportSTDIO, HTTP
AuthRequired
Resources4
Tools verifiedJun 10, 2026
UpdatedMay 12, 2026
