Agent Billy

Agent Billy MCP サーバー

AI アシスタント（Claude、Cursor、Copilot）が、Billy コンテナ API を通じて Stripe の請求情報にロールベースで安全にアクセスできるローカル MCP プロキシです。

クイックスタート

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 キーには、作成時に割り当てたロールが引き継がれます。Billing Clerk キーでは、Billing Clerk の操作のみ実行できます。キーは 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 キーには、作成者のロールが引き継がれます。

ロール	読み取り	返金	サブスクリプション管理	請求書	顧客	クーポン
Owner	すべて	無制限	全権限	全権限	全権限	全権限
Billing Manager	すべて	最大 $5,000	全権限	全権限	全権限	全権限
Billing Clerk	すべて	最大 $100	閲覧のみ	閲覧のみ	更新のみ	なし
Read Only	すべて	なし	なし	なし	なし	なし

支出上限

返金の上限は、ロールごとに取引単位で適用されます。

• Owner： 上限なし
• Billing Manager： 返金 1 件あたり $5,000
• Billing Clerk： 返金 1 件あたり $100
• Read Only： 返金を実行できません

上限を超えようとすると、権限エラーが返されます。操作は監査証跡に記録されます。

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]