ribbo-mcp

Ribbo 的 MCP（Model Context Protocol）服务器。它将您的 AI 助手（Claude Desktop、Cursor 等）连接到 Ribbo 的定期收款 API，并使其成为一个操作员：AI 将执行真实操作 —— 创建和管理订阅、查询 entitlements、退款、立即收款，以及生成支付/续期链接。

身份验证使用您的租户 API 密钥（前缀 bk_），在控制台面板的 开发者 → API keys 中生成。该服务器是公共 API 的精简客户端：代码中不包含任何密钥 —— 您通过环境变量提供自己的密钥。

要求

• Node.js 18+

• 一个 Ribbo 的 API 密钥（bk_…）。使用 read 范围的密钥只能查询；使用 write 范围的密钥可以让 AI 执行操作（退款、收款、取消等）。

Related MCP server: Agent Billy MCP Server

安装

最快的方式 —— 无需克隆任何代码 —— 是通过 npx 将您的 AI 客户端指向该包。要在终端中测试：

# direto do GitHub (funciona já):
npx -y github:andrespadeto/ribbo-mcp

# ou, depois de publicado no npm:
npx -y ribbo-mcp

它会保持等待直到从 stdio 接收数据 —— 这就是 MCP 服务器的运行方式。与之“对话”的是您的 AI 客户端（如下所述），而不是终端。退出请按：Ctrl+C。

配置

两个环境变量：

Claude Desktop

在 claude_desktop_config.json（菜单 → Settings → Developer → Edit Config）中：

{
  "mcpServers": {
    "ribbo": {
      "command": "npx",
      "args": ["-y", "github:andrespadeto/ribbo-mcp"],
      "env": {
        "RIBBO_API_KEY": "bk_sua_chave_aqui",
        "RIBBO_API_BASE": "https://api.ribbo.app"
      }
    }
  }
}

重启 Claude Desktop。Ribbo 的工具会出现在聊天的工具图标中。

Cursor

在 .cursor/mcp.json（项目中）或全局 MCP 设置中，使用上面相同的 mcpServers 块。

发布到 npm 后，将 "github:andrespadeto/ribbo-mcp" 替换为 "ribbo-mcp"。

工具

读取（只需要 read 密钥）：

写入（需要 write 密钥 —— 会改动资金/状态）：

安全性

• 密钥标识并隔离您的租户 —— 其他租户的数据永远无法访问。

• 写操作会改动资金/状态（退款、收款、取消）。如果 AI 只需要查询，请使用 read 密钥；仅在需要实际执行操作时使用 write 密钥。

• 密钥存放在 MCP 客户端的环境变量中（在您的机器上） —— 请将其视为机密，切勿提交。

• 代码开源且不含任何密钥：所有凭据都来自环境变量。

API 约定

金额以分（整数）为单位；ID 带有前缀（sub_、cus_、pay_、ord_ 等）；时间格式为 ISO-8601 UTC。错误格式为 Erro <状态>: {…}。完整契约（OpenAPI 3.1）见 GET {RIBBO_API_BASE}/v1/public/schema/。

开发

git clone https://github.com/andrespadeto/ribbo-mcp.git
cd ribbo-mcp
npm install          # o "prepare" compila o TypeScript para dist/
cp .env.example .env # preencha RIBBO_API_KEY e RIBBO_API_BASE
npm run dev          # build + start

• 源代码在 src/（TypeScript ESM）。src/index.ts 注册工具；src/api.ts 是 HTTP 客户端（Bearer）。

• 构建产物（dist/）由 npm run build 生成，并且不进行版本控制。

许可证

MIT © Ribbo