Agent Billy

Agent Billy MCP 服务

本地 MCP 代理，通过 Billy 容器 API 为 AI 助手（Claude、Cursor、Copilot）提供安全的、基于角色的 Stripe 账单访问权限。

快速开始

npx agent-billy --api-url https://yourorg.agentbilly.ai --api-key billy_your-api-key

也可以使用环境变量：

export BILLY_API_URL=https://yourorg.agentbilly.ai
export BILLY_API_KEY=billy_your-api-key
npx agent-billy

MCP 配置

Claude Desktop

将以下内容添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "agent-billy": {
      "command": "npx",
      "args": ["-y", "agent-billy"],
      "env": {
        "BILLY_API_URL": "https://yourorg.agentbilly.ai",
        "BILLY_API_KEY": "billy_your-api-key"
      }
    }
  }
}

配置文件位置：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows： %APPDATA%\Claude\claude_desktop_config.json

Claude Code

claude mcp add agent-billy \
  -e BILLY_API_URL=https://yourorg.agentbilly.ai \
  -e BILLY_API_KEY=billy_your-api-key \
  -- npx -y agent-billy

Cursor

前往 Settings > MCP Servers > Add new MCP server，并输入：

{
  "command": "npx",
  "args": ["-y", "agent-billy"],
  "env": {
    "BILLY_API_URL": "https://yourorg.agentbilly.ai",
    "BILLY_API_KEY": "billy_your-api-key"
  }
}

VS Code（GitHub Copilot）

将以下内容添加到 settings.json：

{
  "mcp": {
    "servers": {
      "agent-billy": {
        "command": "npx",
        "args": ["-y", "agent-billy"],
        "env": {
          "BILLY_API_URL": "https://yourorg.agentbilly.ai",
          "BILLY_API_KEY": "billy_your-api-key"
        }
      }
    }
  }
}

身份验证

从 Billy 控制面板生成 API 密钥：

1. 登录 https://yourorg.agentbilly.ai
2. 前往 Settings > API Keys
3. 点击 Generate Key 并选择一个角色
4. 复制密钥，并将其用作 BILLY_API_KEY

API 密钥继承创建时分配的角色。账单专员密钥只能执行账单专员的操作。你可以随时在 Settings 中撤销密钥。

可用工具

读取工具

工具	说明
billy_list_charges	列出近期扣款。可按状态筛选（succeeded、failed、pending）。
billy_get_charge	根据 Stripe 扣款 ID 获取特定扣款的详情。
billy_list_customers	分页列出客户。
billy_get_customer	根据 Stripe 客户 ID 获取特定客户的详情。
billy_list_subscriptions	列出订阅。可按状态筛选（active、past_due、canceled、trialing）。
billy_list_invoices	列出发票。可按状态筛选（draft、open、paid、void、uncollectible）。
billy_list_refunds	列出所有已发放的退款。
billy_get_stats	控制面板快照：本月至今的收入、成功率、有效订阅数、失败扣款数。
billy_search	按关键词搜索客户、扣款、订阅和发票。

写入工具

工具	说明
billy_create_refund	为扣款发起全额或部分退款。
billy_create_customer	创建新的 Stripe 客户。
billy_update_customer	更新客户的电子邮件、姓名、说明或元数据。
billy_cancel_subscription	取消订阅（在周期结束时或立即取消）。
billy_reactivate_subscription	重新激活已取消但尚未完全到期的订阅。
billy_send_invoice	通过电子邮件向客户发送发票。
billy_void_invoice	作废发票，使其无法再被支付。
billy_create_coupon	创建折扣优惠券（百分比折扣或固定金额折扣）。
billy_delete_coupon	删除优惠券，使其无法用于新客户。

基于角色的访问控制

所有权限均由服务端强制执行。API 密钥继承创建该密钥的用户角色。

角色	读取	退款	管理订阅	发票	客户	优惠券
所有者	全部	不限	完全权限	完全权限	完全权限	完全权限
账单经理	全部	最高 $5,000	完全权限	完全权限	完全权限	完全权限
账单专员	全部	最高 $100	仅查看	仅查看	仅更新	无
只读	全部	无	无	无	无	无

支出限额

退款限额按角色逐笔交易执行：

• 所有者： 无限制
• 账单经理： 每笔退款最高 $5,000
• 账单专员： 每笔退款最高 $100
• 只读： 无法发起退款

尝试超出限额会返回权限错误。该操作会记录在审计日志中。

CLI 选项

agent-billy --api-url <url> --api-key <key>

Options:
  --api-url   Billy container API URL (or BILLY_API_URL env var)
  --api-key   API key (or BILLY_API_KEY env var)
  --token     JWT auth token, alternative to api-key (or BILLY_TOKEN env var)
  --help, -h  Show help

链接

• 网站：agentbilly.ai
• 文档：agentbilly.ai/docs
• npm：npmjs.com/package/agent-billy
• 支持：[email protected]