mcp-chargebee

@codespar/mcp-chargebee

面向 Chargebee 的 MCP 服务——全球订阅计费编排

为什么 CodeSpar 目录收录 Chargebee？

Chargebee 在支付网关（Stripe、Adyen、Braintree、拉美本地收单机构）之上提供订阅计费编排。它负责套餐、按比例计费、逾期催收、税务和收入确认——这是 SaaS 变现层，而非银行卡处理层。

CodeSpar 目录已收录适用于巴西本土经常性计费的 Vindi 和 Iugu。Chargebee 与它们相辅相成（而非功能重叠）：它采用全球 SaaS 模式，Platzi、Truora 以及大多数向拉美市场销售的美国 SaaS 公司都在使用。功能毫无重叠，面向不同市场。

快速开始

Claude Desktop

添加到 ~/.config/claude/claude_desktop_config.json：

{
  "mcpServers": {
    "chargebee": {
      "command": "npx",
      "args": ["-y", "@codespar/mcp-chargebee"],
      "env": {
        "CHARGEBEE_SITE": "your-site",
        "CHARGEBEE_API_KEY": "your-api-key"
      }
    }
  }
}

Claude Code

claude mcp add chargebee -- npx @codespar/mcp-chargebee

Cursor / VS Code

添加到 .cursor/mcp.json 或 .vscode/mcp.json：

{
  "servers": {
    "chargebee": {
      "command": "npx",
      "args": ["-y", "@codespar/mcp-chargebee"],
      "env": {
        "CHARGEBEE_SITE": "your-site",
        "CHARGEBEE_API_KEY": "your-api-key"
      }
    }
  }
}

工具（15 个）

工具	用途
create_subscription	在 Chargebee 中创建新订阅。
retrieve_subscription	根据 ID 获取订阅
update_subscription	更新订阅。
cancel_subscription	取消订阅。
reactivate_subscription	重新激活已取消或暂停的订阅
list_subscriptions	列出订阅。
create_customer	在 Chargebee 中创建客户。
retrieve_customer	根据 ID 获取客户
update_customer	更新客户。
list_customers	列出客户。
retrieve_invoice	根据 ID 获取发票
list_invoices	列出发票，可使用筛选条件
create_payment_source_using_token	使用网关令牌将支付来源关联到客户（例如
delete_payment_source	删除支付来源
list_events	列出 webhook 事件。

身份验证

Chargebee API v2 使用 HTTP Basic 身份验证，以 API 密钥作为用户名，密码留空。本软件包会自动处理——只需设置 CHARGEBEE_API_KEY。

请求正文采用 application/x-www-form-urlencoded 格式（Chargebee v2 的约定）。嵌套对象和数组会扁平化为 parent[child]=value / parent[0][child]=value。

筛选语法

Chargebee 的列表筛选条件采用 field[operator]=value 格式，例如 status[is]=active、email[is][email protected]、occurred_at[after]=1700000000。

在任何 list_* 工具中，通过 filters 对象传入这些条件：

{
  "filters": {
    "status[is]": "active",
    "plan_id[is]": "pro-monthly"
  }
}

常用列表筛选条件也提供了顶层快捷参数（例如，list_invoices 可直接接受 customer_id、status）。

环境变量

变量	必填	说明
CHARGEBEE_SITE	是	站点子域名，例如 acme-test.chargebee.com 中的 acme-test
CHARGEBEE_API_KEY	是	在 Settings > API Keys 中获取的 API 密钥（完全访问权限或受限权限）

沙盒 / 测试

每个 Chargebee 账户都包含一个免费的测试站点（<your-site>-test.chargebee.com）。开发时请使用其 API 密钥——不会向真实支付网关发起扣款。

获取凭据

1. 在 chargebee.com 注册
2. 系统会自动创建测试站点（<name>-test）
3. 前往 Settings > API Keys，创建一个完全访问权限或只读密钥
4. 设置 CHARGEBEE_SITE 和 CHARGEBEE_API_KEY

路线图

v0.2（计划中）

• create_invoice — 在订阅之外向客户收费
• record_payment — 记录线下付款
• create_coupon / list_coupons
• create_plan / list_plans / create_addon
• list_transactions

v0.3（计划中）

• create_hosted_page_checkout — 生成 Chargebee 托管结账 URL
• retrieve_quote / convert_quote
• 收入报告辅助工具

想更早使用某个工具？提交 issue 或 PR。

链接

• Chargebee 网站
• Chargebee API 文档
• MCP Dev LATAM
• 落地页

企业版

需要对 Agent 发起的订阅变更进行治理、预算限制和审计跟踪？CodeSpar Enterprise 在这些 MCP 服务的基础上，增加了策略引擎、支付路由和合规模板。

许可证

MIT