karbon-mcp-server

Karbon MCP 服务

🚧 早期版本 — 本项目刚刚推出，我们正在未来几天内积极更新。内容可能会快速变化；如果需要稳定性，请固定版本，并记得稍后回来查看。

一个非官方的 Model Context Protocol 服务，用于管理 Karbon 业务。将 Claude Code、Claude Desktop、GitHub Copilot 或任何兼容 MCP 的客户端连接到你的 Karbon 实例，即可用自然语言处理联系人、工作项、工时、发票、付款、文件等。

免责声明： 这是一个社区项目，与 Karbon 无关联，也未获其认可。使用风险由你自行承担。

功能

区域	工具
联系人	list_contacts、get_contact、create_contact、update_contact
组织	list_organizations、get_organization、create_organization、update_organization
客户组	list_client_groups、get_client_group、create_client_group、update_client_group
工作项	list_work_items、get_work_item、get_estimate_summary、create_work_item、update_work_item
备注和评论	get_note、create_note、get_comment
工时表	list_timesheets、get_timesheet、list_time_entries、get_time_entry（只读）
发票	list_invoices、get_invoice（只读）
付款	list_payments、get_payment；以及需通过 KARBON_ALLOW_PAYMENT_WRITES=true 启用的 create_manual_payment、delete_manual_payment、reverse_manual_payment
名片	get_business_card、update_business_card — 联系方式（电子邮件、电话、地址）
自定义字段	list_custom_fields、get_custom_field_values、set_custom_field_values、create_custom_field、delete_custom_field
文件	list_entity_files、download_file、upload_file
团队	list_teams、get_team、add_team_members、remove_team_member
工作计划	get_work_schedule、create_work_schedule、update_work_schedule
用户	list_users、get_user
账户	get_tenant_settings、list_work_templates、get_work_template

get_contact、get_organization 和 get_client_group 也可以使用你自己的 UserDefinedIdentifier（而非 Karbon 键）查找记录 — 如果你要从税务软件同步 ID，这会很方便。

所有列表工具都支持 OData 筛选（$filter）、排序（$orderby）和分页（$top/$skip），因此你可以提出“显示本月到期且正在进行的工作项”之类的请求，AI 会将其转换为精确查询。

前置条件

• Node.js 18+
• Karbon API 凭据。在 Karbon 中前往 Settings → Connected Apps → API Applications，复制你的 Bearer Token 和 Access Key。（Karbon 帮助文章）

设置

Claude Desktop、claude.ai/Cowork 和 ChatGPT 的分步指南（面向非开发者编写）请参阅 docs/client-guides.md。

Claude Desktop：一键安装包

从最新版本下载 karbon-mcp-server.mcpb 并双击。Claude Desktop 会打开一个表单，让你填写两项 Karbon 密钥（由操作系统安全存储），还可切换只读模式——无需使用终端。操作指南。

一行命令安装（无需预先下载）

没有 Node.js？以下命令会检查是否已安装 Node.js（尽可能通过 winget/Homebrew 安装），然后直接从 npm 运行设置向导——无需克隆仓库或手动下载：

# Windows (PowerShell)
irm https://raw.githubusercontent.com/Mad-Man-Dan/karbon-mcp-server/main/scripts/install.ps1 | iex

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/Mad-Man-Dan/karbon-mcp-server/main/scripts/install.sh | bash

已安装 Node.js 时最快的方式：自动设置

npx -y karbon-mcp-server setup

设置过程会询问几个简单问题——选择项目级或用户级安装、填写你的 API 密钥（可以跳过），以及是否启用只读模式——然后自动完成其他所有操作：

• 此项目（默认）：写入 .mcp.json（Claude Code）；如果项目中存在相应文件夹，还会写入 .vscode/mcp.json 和 .cursor/mcp.json。
• 用户账户：检测你的计算机上安装了哪些 MCP 客户端——Claude Code、Codex、Claude Desktop、VS Code、Cursor——并为每个客户端添加服务（对于 Claude Code 和 Codex，则使用它们各自的 mcp add CLI）。

随后，系统会提示你输入两项 Karbon 密钥（按 Enter 可跳过任意一项）：

• 输入内容会隐藏——每个字符显示为一个 *，随后显示前 4 位/后 4 位预览（例如 1a2b****5c6d，与 Karbon 网站使用的格式相同），方便你确认输入内容；如果格式看起来不正确，系统还会发出温和提醒（Bearer Token 是 GUID；Access Key 以 ey... 开头）。
• 密钥只会写入你计算机上 MCP 客户端的本地配置文件，与手动设置时使用的文件相同。它们绝不会发送到其他地方。
• 如果跳过，系统会写入占位值，并准确告知你之后需要编辑哪些文件。

系统会在修改任何现有配置文件前为其创建备份，采用合并而非覆盖的方式，并且绝不会用占位值替换真实凭据（重新运行并跳过提示时会保留现有密钥）。如果选择项目级安装，请将配置文件加入 gitignore——密钥以明文形式保存在其中。

选项：

npx -y karbon-mcp-server setup --scope project          # skip the question
npx -y karbon-mcp-server setup --scope user
npx -y karbon-mcp-server setup --read-only              # disable all write tools
npx -y karbon-mcp-server setup --client vscode,cursor   # only these clients
                    # ids: claude-code, codex, claude-desktop, vscode, cursor
npx -y karbon-mcp-server setup --print                  # just print the JSON

一键安装

上方的 Install in VS Code / Cursor 徽章会为你创建服务条目，并填入占位凭据。安装后，将 YOUR_BEARER_TOKEN 和 YOUR_ACCESS_KEY 替换为真实密钥——在 VS Code 中通过命令面板 → MCP: Open User Configuration 操作；在 Cursor 中编辑 ~/.cursor/mcp.json。

如果尚未替换占位值就运行服务，它仍能正常启动，而且每个工具都会返回设置说明，而不是令人摸不着头脑地失败——因此你甚至可以问 AI 助手“为什么 Karbon 无法正常工作？”，它会告诉你该怎么做。

想手动配置？各客户端的配置如下。

Claude Code

claude mcp add karbon \
  --env KARBON_BEARER_TOKEN=your-bearer-token \
  --env KARBON_ACCESS_KEY=your-access-key \
  -- npx -y karbon-mcp-server

Claude Desktop

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "karbon": {
      "command": "npx",
      "args": ["-y", "karbon-mcp-server"],
      "env": {
        "KARBON_BEARER_TOKEN": "your-bearer-token",
        "KARBON_ACCESS_KEY": "your-access-key"
      }
    }
  }
}

VS Code (GitHub Copilot)

添加到工作区中的 .vscode/mcp.json（或你的用户级 mcp.json）：

{
  "servers": {
    "karbon": {
      "command": "npx",
      "args": ["-y", "karbon-mcp-server"],
      "env": {
        "KARBON_BEARER_TOKEN": "your-bearer-token",
        "KARBON_ACCESS_KEY": "your-access-key"
      }
    }
  }
}

Cursor

添加到 ~/.cursor/mcp.json（或使用上方的安装徽章）：

{
  "mcpServers": {
    "karbon": {
      "command": "npx",
      "args": ["-y", "karbon-mcp-server"],
      "env": {
        "KARBON_BEARER_TOKEN": "your-bearer-token",
        "KARBON_ACCESS_KEY": "your-access-key"
      }
    }
  }
}

Codex (OpenAI Codex CLI)

codex mcp add karbon \
  --env KARBON_BEARER_TOKEN=your-bearer-token \
  --env KARBON_ACCESS_KEY=your-access-key \
  -- npx -y karbon-mcp-server

或者添加到 ~/.codex/config.toml：

[mcp_servers.karbon]
command = "npx"
args = ["-y", "karbon-mcp-server"]

[mcp_servers.karbon.env]
KARBON_BEARER_TOKEN = "your-bearer-token"
KARBON_ACCESS_KEY = "your-access-key"

ChatGPT、claude.ai chat 和 Claude Cowork（远程连接器）

这些客户端无法启动本地服务端——它们只能通过 HTTPS 连接到远程 MCP 服务。此软件包包含适用于此场景的可流式传输 HTTP 模式，因此企业可以自托管服务，并将 Karbon 密钥保存在自己的基础设施中：

KARBON_BEARER_TOKEN=... KARBON_ACCESS_KEY=... KARBON_HTTP_SECRET=some-long-random-string \
  npx -y karbon-mcp-server --http --port 8787

此模式会在 /mcp/<your-secret> 提供 MCP 端点（以及 /health 健康检查）。你可以通过任意方式将其暴露到 HTTPS 上——最快捷的免费方案是使用 Cloudflare Tunnel：

cloudflared tunnel --url http://localhost:8787

然后将 URL（例如 https://your-tunnel.trycloudflare.com/mcp/your-secret）添加为：

• claude.ai / Cowork：Settings → Connectors → Add custom connector（适用于 Pro/Max/Team/Enterprise 计划）
• ChatGPT：Settings → Connectors（如需完整工具访问权限，必须启用开发者模式）

**安全注意事项：**任何人只要拥有完整 URL，就能获得与你的 API 密钥相同的 Karbon 访问权限，因此请使用足够长的随机 KARBON_HTTP_SECRET，始终通过 HTTPS 对外提供服务，并考虑在远程使用时设置 KARBON_READ_ONLY=true。本项目刻意不提供共享或托管的服务实例——你的密钥应始终只保存在你控制的基础设施中。

配置

环境变量	必需	说明
KARBON_BEARER_TOKEN	是	来自 Karbon Connected Apps 的 Bearer 令牌
KARBON_ACCESS_KEY	是	来自 Karbon Connected Apps 的访问密钥（JWT）
KARBON_READ_ONLY	否	设置为 true 可禁用所有创建/更新工具
KARBON_ALLOW_PAYMENT_WRITES	否	设置为 true 可启用付款写入工具（创建/删除/冲销手动付款）。默认关闭
KARBON_API_BASE_URL	否	覆盖 API 基础 URL（默认为 https://api.karbonhq.com/v3）
KARBON_HTTP_SECRET	否	仅限 HTTP 模式：端点的密钥路径段（/mcp/<secret>）
PORT	否	仅限 HTTP 模式：监听端口（默认为 8787；--port 优先）

只读模式

如果你希望确保 AI 永远无法修改 Karbon 数据，请设置 KARBON_READ_ONLY=true（或传入 --read-only）。此模式下不会注册写入工具，因此 AI 根本看不到这些工具。此模式也会禁用 download_file——它不会修改 Karbon，但会写入本地磁盘，而只读意味着任何地方都不允许写入。设置向导会询问是否启用此模式。

**之后更改：**设置程序始终会明确写入此开关（"KARBON_READ_ONLY": "true" 或 "KARBON_READ_ONLY": "false"），因此可以直接在配置文件中找到并切换该值，然后重启客户端。写入工具会相应地出现或消失（只读模式下不会注册这些工具，因此 AI 根本看不到它们）。或者，重新运行设置程序并跳过密钥提示（按 Enter）——已保存的密钥会保留，并应用新的只读设置。请注意：重新运行设置程序不会修改由 claude / codex CLI 管理的条目——对于这些条目，请先运行 claude mcp remove karbon（或 codex mcp remove karbon），再重新运行设置程序。

付款写入（需额外主动启用）

记录、删除或冲销付款会影响财务记录，因此这三个工具各自设有独立开关——即使已启用其他写入功能，也只有在设置 KARBON_ALLOW_PAYMENT_WRITES=true（或传入 --allow-payment-writes）后才会注册。设置程序会将此开关写为 "false"，方便你在配置文件中找到并切换；重新运行设置程序时，不会重置你手动更改过的值。只读模式始终优先：如果 KARBON_READ_ONLY=true，付款写入功能就会保持关闭。

关于凭据的说明

无论你是在设置向导中输入密钥，还是手动将密钥粘贴到配置文件中，它们最终都只会存储在一个地方：你自己的 MCP 客户端本地配置文件中——也就是完全手动设置时会使用的同一个文件。此项目不会将你的密钥传输到其他任何地方。与所有 stdio MCP 服务一样，密钥会以纯文本形式保存在该文件中，因此请像对待密码一样保管它：它能授予与你的密钥相同的 Karbon 账户访问权限。如果密钥泄露，请在 Karbon 的“Settings → Connected Apps”下重新生成。

示例提示词

• “查找 Jane Smith 的联系人记录，并显示她的名片详情。”
• “更新 Jane Smith 的电子邮件地址和电话号码。”
• “列出分配给我的所有进行中工作项，并按截止日期排序。”
• “Henderson 一家的税务申报是否超出预算了？”
• “哪些发票仍待付款？金额分别是多少？”
• “为 Acme Corp 的 2025 年税务申报创建一个工作项，分配给 [email protected]，并从下周一开始。”
• “在 Smith 工作项中添加一条备注，总结今天的客户通话。”
• “上周记录了多少小时的客户工作时间？”
• “Miller 入职工作项附有哪些文件？”

开发

git clone https://github.com/Mad-Man-Dan/karbon-mcp-server.git
cd karbon-mcp-server
npm install
npm test        # builds, then runs the smoke tests (tool matrix across flag combos)

发布流程已自动化：推送 v* 标签会运行 CI，通过 trusted publishing（OIDC——无需令牌）发布到 npm，并更新 MCP Registry 中的条目。

使用 MCP Inspector 在本地进行测试：

npx @modelcontextprotocol/inspector \
  -e KARBON_BEARER_TOKEN=... -e KARBON_ACCESS_KEY=... \
  node dist/index.js

Karbon API 的文档位于 developers.karbonhq.com，OpenAPI 规范位于 karbonhq/karbon-api-reference。

贡献

欢迎贡献——请提交 issue 或 PR。

许可证

MIT