MCP 服务器

Agent Billy MCP Server

Provides secure, role-based access to Stripe billing operations for AI assistants like Claude and Cursor. It enables users to manage customers, subscriptions, invoices, and refunds through a local proxy with server-side permission enforcement.

README

Agent Billy MCP Server

Local MCP proxy that gives AI assistants (Claude, Cursor, Copilot) secure, role-based access to your Stripe billing through your Billy container API.

Quick Start

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

Or use environment variables:

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

MCP Configuration

Claude Desktop

Add to your 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"
      }
    }
  }
}

Config file locations:

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

Go to Settings > MCP Servers > Add new MCP server and enter:

{
  "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)

Add to your 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"
        }
      }
    }
  }
}

Authentication

Generate an API key from your Billy dashboard:

Log in at https://yourorg.agentbilly.ai
Go to Settings > API Keys
Click Generate Key and choose a role
Copy the key and use it as your BILLY_API_KEY

API keys inherit the role you assign when creating them. A Billing Clerk key can only perform Billing Clerk actions. Keys can be revoked at any time from Settings.

Available Tools

Read Tools

Tool	Description
`billy_list_charges`	List recent charges. Filter by status (succeeded, failed, pending).
`billy_get_charge`	Get details for a specific charge by Stripe charge ID.
`billy_list_customers`	List customers with pagination.
`billy_get_customer`	Get details for a specific customer by Stripe customer ID.
`billy_list_subscriptions`	List subscriptions. Filter by status (active, past_due, canceled, trialing).
`billy_list_invoices`	List invoices. Filter by status (draft, open, paid, void, uncollectible).
`billy_list_refunds`	List all refunds that have been issued.
`billy_get_stats`	Dashboard snapshot: MTD revenue, success rate, active subs, failed charges.
`billy_search`	Search across customers, charges, subscriptions, and invoices by keyword.

Write Tools

Tool	Description
`billy_create_refund`	Issue a full or partial refund for a charge.
`billy_create_customer`	Create a new Stripe customer.
`billy_update_customer`	Update a customer's email, name, description, or metadata.
`billy_cancel_subscription`	Cancel a subscription (at period end or immediately).
`billy_reactivate_subscription`	Reactivate a canceled subscription that hasn't fully expired.
`billy_send_invoice`	Send an invoice to the customer via email.
`billy_void_invoice`	Void an invoice so it can no longer be paid.
`billy_create_coupon`	Create a discount coupon (percentage or fixed amount).
`billy_delete_coupon`	Delete a coupon so it can't be applied to new customers.

Role-Based Access

All permissions are enforced server-side. The API key inherits the role of the user who created it.

Role	Read	Refunds	Manage Subs	Invoices	Customers	Coupons
Owner	All	Unlimited	Full	Full	Full	Full
Billing Manager	All	Up to $5,000	Full	Full	Full	Full
Billing Clerk	All	Up to $100	View only	View only	Update only	No
Read Only	All	No	No	No	No	No

Spending Limits

Refund limits are enforced per transaction, per role:

Owner: No limit
Billing Manager: $5,000 per refund
Billing Clerk: $100 per refund
Read Only: Cannot issue refunds

Attempting to exceed your limit returns a permission error. The action is logged in the audit trail.

CLI Options

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