Carbone

Carbone MCP Server

通过模板和 JSON 数据，从 Claude、Cursor、VS Code 或任何 MCP 客户端自动生成可用于生产环境的 PDF、Word、Excel 和 PowerPoint 文档，并在 100 多种格式之间转换文件。这是 Carbone 文档生成 API 的官方服务。

• **转换文件：**将 DOCX、XLSX、PPTX、HTML、Markdown 或 PDF 转换为 PDF、图像、CSV、ODT 以及其他输出格式。
• **用 JSON 填充模板：**在 Word、Excel、PowerPoint、LibreOffice、HTML 或 Markdown 中使用 {d.field} 标签设计模板，或填写现有 PDF 表单。
• **完善 PDF：**设置密码、水印、PDF/A、页码范围，并选择转换器（LibreOffice、OnlyOffice、Chromium 或 Carbone ICE）。
• **批量处理和本地化：**每个请求最多处理 100 份文档，并将结果发送到你的 webhook；提供翻译、时区和按你指定汇率进行的货币转换。
• **管理模板库：**上传、版本管理、分类、部署和下载模板，并查询模板所需的数据。

你可以提出的请求

这些功能适用于任何 Carbone 账户，即使没有套餐也能使用（此时生成的 PDF 会带有水印）：

• “将这段 Markdown 转换为 PDF：# 季度更新 …”
• “用这份 JSON 填充我的发票模板，并生成 PDF：{"customer": "Acme", "total": 1500}"
• “这份合同模板需要哪些数据？”（inspect_template 会列出模板标签并起草一份示例 JSON）

更多示例见示例提示词，包括使用 Salesforce、HubSpot、Notion 和 Stripe 的示例。

快速开始

从 1.x 升级？请阅读升级说明——HTTP 部署应立即升级（包含安全修复）。

先决条件

• Carbone 账户：account.carbone.io。托管服务会使用该账户为你登录；账户拥有套餐（包括 Free 套餐）后，将使用生产密钥，在此之前则使用测试密钥。本地软件包和 Docker 会直接使用其中一个密钥（详情）：
  • 测试密钥：可免费生成不限量的带水印 PDF（仅支持 PDF 输出）。使用该密钥存储的模板最多保留 30 天。
  • 生产密钥：支持任意输出格式，且不带水印。Free 套餐每月包含 100 份文档。
• Node.js 20.3 或更高版本，用于本地软件包（npx carbone-mcp）。使用 node --version 检查。Docker 镜像仅需 Docker。

选择设置方式

设置方式	运行方式	客户端	本地文件
托管服务（HTTP）	https://mcp.carbone.io，无需安装	claude.ai、Claude Desktop、Claude Code、VS Code、Cursor 等：使用 Carbone 账户登录	❌ 仅支持 URL 和 base64
本地软件包（stdio）	在你的机器上运行 npx carbone-mcp	Claude Desktop、Claude Code、VS Code、Cursor，以及任何能够启动本地服务的客户端	✅ 读取本地路径，将文档保存到磁盘
Docker（HTTP）	你自己的服务	能发送 Authorization 请求头的客户端：Claude Code、VS Code、Cursor 等	❌ 仅支持 URL 和 base64

**claude.ai 和 Claude Desktop：**将托管服务添加为连接器。在 Claude Desktop 中，如果要读取和保存电脑上的文件，请改用本地软件包。

本地包（stdio）

大多数客户端使用此配置：

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

客户端	放置位置
Claude Desktop	Settings → Developer → Edit Config 会打开 claude_desktop_config.json（macOS：~/Library/Application Support/Claude/，Windows：%APPDATA%\Claude\）。之后退出并重新启动 Claude Desktop。
Cursor	~/.cursor/mcp.json（所有项目）或 .cursor/mcp.json（单个项目）

Claude Code：

claude mcp add --env CARBONE_API_KEY=your_api_key_here --transport stdio carbone -- npx -y carbone-mcp

VS Code： .vscode/mcp.json 使用 servers，而不是 mcpServers。使用输入变量时，VS Code 会要求输入一次密钥，并将其安全存储：

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

然后试试：“Carbone 能做什么？”

客户端文档：Claude Desktop · Claude Code · VS Code · Cursor

托管服务（mcp.carbone.io）

无需安装：通过 Streamable HTTP 连接到 https://mcp.carbone.io，并在客户端于浏览器中打开 account.carbone.io 时使用你的 Carbone 账号登录。通过 HTTP 传递文件输入时，必须使用 URL 或 base64（文件输入）。

Claude Code： 添加服务，然后运行 /mcp，选择 carbone 并选择 Authenticate。

claude mcp add --transport http carbone https://mcp.carbone.io

VS Code（.vscode/mcp.json），在启动服务时会要求你登录：

{
  "servers": {
    "carbone": { "type": "http", "url": "https://mcp.carbone.io" }
  }
}

Cursor（~/.cursor/mcp.json 或 .cursor/mcp.json），然后在 Cursor 的 MCP 设置中登录：

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

claude.ai 和 Claude Desktop 连接器

1. 添加一个自定义连接器，URL 为 https://mcp.carbone.io。OAuth 客户端 ID 和密钥留空。
2. 点击 Connect，使用你的 Carbone 账号登录并批准。

在组织中，每位成员都使用自己的 Carbone 账号连接，其文档用量计入该账号。Claude Desktop 使用相同的连接器；若要在电脑上读取和保存文件，请改用本地包。

文件输入与输出

文件输入

file（convert_document）和 template（render_document、inspect_template、upload_template）接受：

格式	示例	stdio	HTTP
绝对本地路径	/Users/me/invoice.docx、~/invoice.docx、C:\Users\me\invoice.docx	✅	❌ 不接受
URL	https://example.com/invoice.docx	✅	✅
Base64	文件内容，以 base64 编码	✅	✅

任何其他字符串（例如不带路径的 invoice.docx）都会被当作 base64 读取并导致失败。相对路径（./…、../…）会相对于服务的工作目录解析，该目录由客户端选择；建议使用绝对路径。JSON 参数（data、complement 等）也接受指向 JSON 文件的路径、URL 或 base64 字符串（详情）。

输出交付

输出	stdio（本地客户端）	HTTP（远程 / 可自托管）
文本：HTML、TXT、CSV、MD、XML、JSON（模板示例）	内嵌文本	内嵌文本
图像：PNG、JPG、GIF、WEBP	内嵌图像	内嵌图像
其他所有格式：PDF、Office、SVG、TIFF…	保存到临时文件，并返回路径	作为下载附件返回

你也可以指定路径保存文件（outputPath，仅限 stdio）、将任意格式作为附件获取（asAttachment），或获取一次性下载链接（returnLink）：参见输出与文件交付。

Claude Desktop 无法显示内嵌的二进制附件（会将其错误处理为图像）。对于 PDF 和 Office 文件，请保留默认的临时文件路径，或请求 returnLink 以获取下载 URL。

工具

工具	功能
convert_document	将文件转换为其他格式；Carbone 标签保持原样
render_document	使用 JSON 数据填充模板，并可转换结果（例如转换为 PDF）
inspect_template	列出模板的标签并返回匹配的示例数据集。在你的账户上执行一次渲染（计为一次文档生成）
list_templates	按类别、名称或 ID 列出已存储的模板
list_categories	列出你账户中的模板类别
list_tags	列出所有模板中使用的标签
upload_template	存储可重复使用的模板，并包含版本、类别和标签
update_template_metadata	重命名模板版本、设置类别和标签、部署模板版本，或安排删除模板版本
delete_template	立即删除模板或其某个版本
download_template	下载模板的原始文件，或与其一同存储的示例数据
get_api_status	检查 Carbone API 的运行状况和版本
get_capabilities	概述格式、功能和使用示例

所有参数及示例：docs/API.md。

示例提示词

与其他工具搭配使用。 Carbone 可将其他 MCP 服务获取的数据转换为完整文档。以下示例假设该服务（Salesforce、HubSpot、Notion、Stripe，……）已连接到同一客户端。

• “从 Salesforce 获取 Acme Corp 的商机及其产品，填入我的‘销售报价’模板，并提供 PDF”
• “对于本周进入 Closed Won 阶段的每笔 HubSpot 交易，填入‘服务协议’模板，并将 PDF 保存到 ~/Contracts”
• “检查我的‘发票’模板，将其字段映射到 HubSpot 交易‘Acme renewal’，并在渲染前向我展示 JSON”
• “收集 Notion‘Sprint 42’数据库中标记为 Done 的任务，并将其填入我们的‘迭代报告’模板，生成 DOCX”
• “列出 Acme Corp 上个月已付款的 Stripe 发票，并使用‘对账单’模板生成账户对账单”
• “从‘Workshop’ Google 表格读取参会者名单，并使用‘证书’模板为每位参会者创建一份证书”
• “将本周在 GitHub 上合并的拉取请求汇总到我们的‘发布说明’模板中，然后在 Slack 的 #releases 频道发布两行摘要”

模板和数据

• “使用模板 1530905183164918624 和 {customer: 'Acme Corp', total: 1500, items: [...]} 生成发票”
• “用 ~/hr/jane-doe.json 填充 ~/templates/offer-letter.docx，并将 PDF 保存为 ~/Documents/offer-jane-doe.pdf”
• “将模板 1530905183164918624 显示为 PDF，并保留可见的标签，方便我检查版式”

转换

• “使用 Carbone ICE 转换器将 /Users/me/contracts/contract.docx 转换为 PDF”
• “将 https://example.com/sales.xlsx 转换为以分号分隔的 CSV”
• “将此 PDF 渲染为 PNG 缩略图”

批量处理和本地化

• “为 ~/data/invoices.json 中的每位客户创建一张发票，将文件打包为 ZIP，文件名为 invoice-{d.id}，并发送到我的 webhook https://example.com/hook”
• “使用同一模板生成法语、德语和西班牙语版本的这张发票”
• “渲染报告，将价格按 1.08 的汇率从 EUR 转换为 USD，并将日期设为纽约时间”

PDF 选项和模板库

• “将此 DOCX 转换为 PDF，设置打开密码 ‘secret123’，并添加不透明度为 20% 的 DRAFT 水印”
• “将此 NDA 的第 1 至 5 页制作成 PDF/A-2b 副本以供存档”
• “部署我的发票模板的最新版本，并安排在 30 天后删除旧版本”

故障排查

症状	原因和解决方法
工具报错 Authentication failed: …（未设置密钥，或 Carbone API 拒绝该密钥并返回 401）	**stdio：**在客户端配置的 env 中设置 CARBONE_API_KEY，然后重启客户端（未设置时，服务会在启动时停止，并提示 CARBONE_API_KEY environment variable is required）。**自托管 HTTP：**发送 Authorization: Bearer <key>；启用 CARBONE_REQUIRE_CLIENT_AUTH_HEADER=true 的服务要求每个请求都带上该标头。在 account.carbone.io 检查密钥。
mcp.carbone.io 要求你重新登录，或登录失败	重新连接：在 Claude 中，先断开连接，再连接该连接器；在 Claude Code 中，选择 /mcp → 清除身份验证，然后选择进行身份验证。
HTTP 403 Invalid Origin: <host>	基于浏览器的客户端从 localhost 以外的主机提供服务。将其主机名添加到 MCP_ALLOWED_ORIGINS。
在浏览器中打开端点时出现 HTTP 405 Method not allowed	这是预期行为：该端点只响应 MCP POST 请求。请使用 MCP 客户端连接；使用 GET /health 检查服务。
出现 HTTP 413 Request body too large，或 stdio 连接关闭	单条 MCP 消息超过了 MCP_MAX_BODY_BYTES（默认值为 60 MB；该限制也适用于 stdio 消息）。请通过 URL（stdio 中也可使用本地路径）传递大文件，而不要内联使用 base64；也可以提高限制。
Rate limit exceeded. Please wait N second(s)	Carbone API 返回了 429。请等待指定时间后重试。
输出中仍可看到 {d.name} 等标签	convert_document 只负责转换，会保留标签。请使用 render_document 并提供数据。
所有 PDF 都带水印，或只有 PDF 能正常工作	你使用的是测试密钥：该密钥只会生成带水印的 PDF。在 mcp.carbone.io 上，请在 account.carbone.io 开通套餐（Free 套餐即可）：服务会自动切换为你的生产密钥。在本地，请使用生产密钥。
使用名称（invoice.docx）指定的文件无法处理	裸文件名会被视为 base64。请传入绝对路径（stdio）、URL 或 base64（文件输入）。
上传后，按模板 ID 渲染仍使用旧版本	按模板 ID 渲染时会使用已部署版本（deployedAt 最新的版本）。请使用 update_template_metadata 部署新版本（templateId = 其版本 ID，deployedAt = 42000000000），或按版本 ID 渲染。
PDF 缺少密码、水印或 PDF/A	PDF/A、页面范围和无障碍功能使用默认转换器 L（LibreOffice）；O、C 和 I 会应用密码、权限和水印。对于 PDF → PDF，服务会自动为你设置 hardRefresh：不要传入 hardRefresh: false。
Claude Desktop 中看不到 Carbone 工具，或服务断开连接	请在 ~/Library/Logs/Claude/（macOS）或 %APPDATA%\Claude\logs\（Windows）中查看 mcp-server-carbone.log（服务的 stderr）。正常启动时会记录 Carbone MCP Server v<version> started (stdio)。
你想在不使用 AI 客户端的情况下测试服务	运行 MCP Inspector（Node.js 22.19+）：npx @modelcontextprotocol/inspector -e CARBONE_API_KEY=your_api_key_here npx carbone-mcp。它会列出工具，并显示每个请求和响应。

自托管

Docker

该镜像在端口 3000 上提供 Streamable HTTP。此快速入门不设置服务器密钥：每个客户端都在 Authorization: Bearer <key> 中发送自己的密钥（使用 Carbone 账号登录仅适用于 mcp.carbone.io），并且该端口只能从你的计算机访问。

docker run -d --name carbone-mcp -p 127.0.0.1:3000:3000 carbone/carbone-mcp
curl http://localhost:3000/health

在 Authorization 标头中填入你的密钥，以连接客户端：

claude mcp add --transport http carbone http://localhost:3000 --header "Authorization: Bearer your_api_key_here"

在 VS Code 和 Cursor 中，使用托管服务配置，将 URL 设为 http://localhost:3000，并在 "url" 旁添加 "headers": { "Authorization": "Bearer your_api_key_here" }。VS Code 可通过类型为 promptString 的 inputs 条目提示输入密钥（"Bearer ${input:carbone-api-key}"），Cursor 则可从环境变量中读取密钥（"Bearer ${env:CARBONE_API_KEY}"）。若要为其他计算机提供服务，请在 TLS 反向代理后发布端口，保持服务器未设置 CARBONE_API_KEY（或设置 CARBONE_REQUIRE_CLIENT_AUTH_HEADER=true），并在 MCP_ALLOWED_ORIGINS 中列出基于浏览器的客户端主机名。

共享密钥变体，适用于一台计算机上的单个用户。 设置服务器级密钥后，客户端无需发送密钥即可连接：

docker run -d --name carbone-mcp -p 127.0.0.1:3000:3000 -e CARBONE_API_KEY=your_api_key_here carbone/carbone-mcp

使用前请阅读共享密钥警告。

Docker Compose： compose.yml 会根据此仓库构建镜像，仅绑定到 127.0.0.1，不设置服务器密钥，并传递 .env.example 中的所有变量。使用 docker compose up -d 启动。Compose 也会从 shell 或 .env 文件读取 CARBONE_API_KEY：如果其中设置了该变量，你将使用共享密钥变体。

如需将镜像作为 Claude Desktop 的 stdio 服务运行，请参阅 Docker Hub 页面。

本地部署 Carbone

如果你运行的是 本地部署的 Carbone，请使用 CARBONE_BASE_URL 将服务指向你的实例；无需 API 密钥。例如，运行 CARBONE_BASE_URL=https://your-carbone-server.com npx carbone-mcp，或在 docker run 中添加 -e CARBONE_BASE_URL=https://your-carbone-server.com。

配置

变量	默认值	用途
CARBONE_API_KEY	无	你的 Carbone API 密钥：在 stdio 模式下使用 Carbone Cloud 时必需；通过 HTTP 使用时可选（安全）
CARBONE_BASE_URL	https://api.carbone.io	Carbone API URL；将其设为本地部署的实例（无需密钥）
CARBONE_TIMEOUT	60000	Carbone API 请求超时（毫秒）；Carbone Cloud 自身的限制为 60 s
CARBONE_MAX_FILE_BYTES	104857600 (100 MB)	从路径、URL 或 base64 读取的最大输入文件大小
MCP_TRANSPORT	stdio（Docker 中为 http）	stdio 或 http
MCP_PORT	3000	HTTP 端口
MCP_PATH	/	HTTP 端点路径；不能为 /health
MCP_MAX_BODY_BYTES	62914560 (60 MB)	最大 MCP 消息大小：HTTP 请求体（超过此值将返回 413）或 stdio 消息
MCP_ALLOWED_ORIGINS	无（始终允许 localhost）	HTTP：允许访问的浏览器 Origin 主机名，以逗号分隔
CARBONE_REQUIRE_CLIENT_AUTH_HEADER	false	HTTP：设为 true 时，拒绝未携带自身 Bearer 密钥的请求
CARBONE_ALLOW_PRIVATE_NETWORK	false	设为 true 时，允许 URL 输入访问私有和内部地址

完整说明：docs/API.md 中的配置。

安全

• URL 输入和本地文件。 除非设置了 CARBONE_ALLOW_PRIVATE_NETWORK=true，否则会拒绝解析到私有或内部地址（localhost、RFC 1918、云元数据）的 URL（详情）。仅在 stdio 模式下读取本地路径，此时服务以你的身份运行；通过 HTTP 访问时则会拒绝读取。
• 共享服务密钥（HTTP）。 如果 HTTP 服务设置了 CARBONE_API_KEY，且 CARBONE_REQUIRE_CLIENT_AUTH_HEADER=false（默认值），那么每个未携带 Bearer 密钥的请求都会使用该密钥：任何能访问此端口的人都能使用该 Carbone 账户。服务启动时会打印警告。切勿将此类端口暴露在你无法完全信任的网络上；或者设置 CARBONE_REQUIRE_CLIENT_AUTH_HEADER=true，要求每个客户端都携带自己的密钥。如果未设置服务密钥（例如未启用身份验证的本地部署 Carbone），则不受此限制。
• 浏览器来源（HTTP）。 如果请求带有 Origin 标头，但该来源不在允许列表中，服务会返回 403，以防恶意网页访问本地运行的服务（DNS 重绑定）并使用其密钥。允许 localhost、127.0.0.1 和 [::1]；请在 MCP_ALLOWED_ORIGINS 中列出你信任的基于浏览器的客户端。不带 Origin 的请求（来自桌面、命令行和服务端客户端）不受影响。
• 提示词注入。 文档或模板可能包含指令，诱使 AI 执行非预期操作，例如将数据发送到其他地方或删除模板。确认工具调用前，请检查客户端即将执行的操作。
• API 密钥。 请勿将密钥纳入版本控制；通过客户端的机密输入或环境变量传入，并在 account.carbone.io 轮换密钥。
• 你的数据。 Carbone 会存储你上传的模板和样例，并保留通过 returnLink 或 Webhook 渲染的文档，直至这些文档被下载。请参阅隐私政策，或运行本地部署的 Carbone以完全掌控数据。

编写模板

在 Word、Excel、PowerPoint、LibreOffice、HTML 或 Markdown 中设计模板，并在需要填入数据的位置添加标签：

Dear {d.customer.name},
Your invoice total is {d.total:formatC()}.
Items:
{d.items[i].description}  {d.items[i].quantity}x  {d.items[i].price:formatC()}
{d.items[i+1]}

{d.items[i]} … {d.items[i+1]} 会为每个项目重复一行。请从基础知识开始，或为你的 AI 助手提供 Carbone Skill，这是面向 AI 工具的模板语法参考（下载 .skill · GitHub）。

贡献

欢迎提交 Bug 报告、修复和文档改进。CONTRIBUTING.md 介绍了开发环境设置、测试、调试和拉取请求流程。

支持

• 文档： MCP 服务 · HTTP API · 模板设计 · OpenAPI 规范
• Bug 和功能请求： GitHub Issues
• 问题咨询： 在 carbone.io 上使用实时聊天（右下角小组件） · 企业服务： [email protected]

许可证

Apache 2.0，详见 LICENSE。