chargebee-mcp

Chargebee MCP Service — a stateless HTTP MCP server wrapping the Chargebee REST API v2 for account/customer management use cases (company records, personnel/contacts, subscription lookups, and financial reporting lookups).

Tech stack: Python 3.12 + uv + FastMCP (Starlette/Uvicorn)

Scope

Chargebee's official MCP Server offering (the "Data Lookup MCP Server") was evaluated first and found unsuitable as a replacement: it is read-only, covers roughly a dozen resource categories, and is missing Coupons, the Item/Item Price/Item Family product-catalog resources, and Upcoming Invoice Estimates entirely — none of which can be added on top of it. This service instead wraps the full Chargebee REST API directly.

Out of Chargebee's ~438 REST API operations across 77 resources, this service started at 30 tools selected for account/company/personnel/report management use cases, then was trimmed down to the 10 core tools below (user-confirmed reduction — dropped delete/merge/payment-role/hierarchy on customers, all contact write ops, subscription create/update/pause/resume/reactivate/term-end/scheduled-changes, all payment-source tools, and invoice-retrieve/credit-notes from reports):

Related MCP server: sherweb-mcp

Quick Start

# Install dependencies
cd D:\claude\project\chargebee-mcp
uv sync

# Run in stdio mode (for Claude Desktop)
$env:CHARGEBEE_SITE="your-site"
$env:CHARGEBEE_API_KEY="your_api_key"
uv run chargebee-mcp

Configuration

Copy .env.example to .env and fill in your values:

Get your API key: Chargebee Billing → Settings → Configure Chargebee → API Keys and Webhooks → API Keys tab.

HEADER 授权参数说明

Gateway 模式下，每个请求必须携带以下两个 HTTP Header：

Claude Desktop Setup

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "chargebee": {
      "command": "uv",
      "args": ["run", "--directory", "D:/claude/project/chargebee-mcp", "chargebee-mcp"],
      "env": {
        "CHARGEBEE_SITE": "your-site",
        "CHARGEBEE_API_KEY": "your_api_key"
      }
    }
  }
}

Transport Modes

stdio (Claude Desktop / CLI)

$env:CHARGEBEE_SITE="your-site"
$env:CHARGEBEE_API_KEY="your_api_key"
uv run chargebee-mcp

HTTP — single-tenant

$env:CHARGEBEE_SITE="your-site"
$env:CHARGEBEE_API_KEY="your_api_key"
$env:MCP_TRANSPORT="http"
$env:AUTH_MODE="env"
uv run chargebee-mcp

HTTP — gateway / multi-tenant

$env:MCP_TRANSPORT="http"
$env:AUTH_MODE="gateway"
uv run chargebee-mcp
# Each request must include: X-Chargebee-Site and X-Chargebee-Api-Key headers

Available Tools (10)

Company (Customer) — 4

Personnel (Customer Contacts) — 1

Account (Subscription) — 3

Report (Invoices / Transactions) — 2

Filter parameters

Chargebee's list endpoints use compound filter query keys with an operator suffix, e.g. email[is]=a@b.com, created_at[after]=1700000000, status[in]=["active","paused"]. Rather than expanding every field × operator combination into separate function parameters, list tools accept an optional filters: dict[str, str] argument — pass the literal Chargebee query key (including the [operator] suffix) as the dict key. Supported fields per resource are documented in each tool's docstring; supported operators are [is], [is_not], [starts_with], [in], [not_in], [between], [after], [before], [on], [none], [is_present] (availability varies by field type — see Chargebee's filter documentation).

Request encoding

Chargebee's REST API uses application/x-www-form-urlencoded request bodies, not JSON. Nested object parameters (billing_address, meta_data) are accepted as plain Python dict and flattened server-side into Chargebee's bracket-notation form fields (billing_address[line1]=...) — see _flatten_form() in api_client.py. _flatten_form() also supports flattening lists and "array of hashes" fields (Chargebee's field[subfield][index]=value convention), but none of the current 10 tools take such a parameter — that code path is currently unexercised.

Known Gaps

• Verified against a live Chargebee account. Using a real production API key + site: chargebee_list_customers, chargebee_retrieve_customer, chargebee_list_customer_contacts, chargebee_list_subscriptions, chargebee_list_invoices, and chargebee_list_transactions all returned real data (200) through the running service. Gateway 401 gating was re-confirmed with a fresh MCP session + an invalid API key (correctly rejected by Chargebee with api_authentication_invalid_key).

• Write operations (chargebee_create_customer, chargebee_update_customer, chargebee_cancel_subscription) have not been exercised end-to-end — only verified structurally (schema, request construction). This was a deliberate choice during self-test: the only available credentials are for MSPbots' own live production Chargebee site, and mutating real billing/subscription data to self-test was avoided. If write-path verification is needed, test against a Chargebee test site (not a live/production API key).

• Nested fields (billing_address, meta_data) are accepted as generic dict rather than fully-typed sub-schemas — callers must know Chargebee's field names for these substructures (documented in each tool's docstring where practical, otherwise see the Chargebee API reference).

• List-endpoint filters are not expanded into named parameters (see "Filter parameters" above) — this keeps the tool count/signature size manageable but pushes filter-key correctness onto the caller.

• Scope is limited to the 10 operations above (company/personnel/account/report management, user-trimmed down from an initial 30). Everything else — Coupons, Items/Item Prices/Item Families, Estimates, Orders, Payment Sources, Credit Notes, subscription create/update/pause/resume/reactivate, customer delete/merge/hierarchy, contact write ops, etc. — is out of scope per user-confirmed selection.

API Reference

• Chargebee API Documentation

• Chargebee OpenAPI Specification (chargebee_api_v2_pc_v2_spec.json — API v2 + Product Catalog v2, used as the source of truth for this service)

• Chargebee Official MCP Servers (evaluated and found insufficient — see Scope above)