Stripe MCP Server

MCP (Model Context Protocol) server that exposes the Stripe API to Claude. Designed to be deployed on Railway in read-only mode.

👉 Deployment steps are in DEPLOY-RAILWAY.md.

What it does

Gives Claude 17 tools to query Stripe: customers, charges, payments, subscriptions, invoices, catalog, balance, transactions, payouts, events, and disputes — plus a generic tool that hits any endpoint, another that resolves any object by its id, and an aggregated revenue report.

Related MCP server: Stripe MCP Server

Environment variables

The three write gates

Stripe moves real money: a wrong POST refunds a customer, cancels a subscription, or deletes a record forever. That's why there are three independent locks, and a write has to pass through all three.

1. STRIPE_READ_ONLY — the default depends on the transport

• stdio (local): writes allowed by default. A single trusted user on their own machine.

• http (remote): writes blocked by default. You have to set STRIPE_READ_ONLY=0 deliberately to enable them.

Forgetting the variable on a public deployment leaves it read-only, not open.

2. STRIPE_ALLOW_LIVE_WRITES — the live-mode gate

Even if you turn off read-only, a live key still rejects writes until you set STRIPE_ALLOW_LIVE_WRITES=1. Test keys (sk_test_, rk_test_) don't go through this gate: experimenting against test data shouldn't require ceremony.

3. confirm=true — the per-endpoint gate

Destructive endpoints (/v1/refunds, /v1/payouts, /v1/transfers, subscription cancellations, customer deletion, dispute closure) require confirm=true in the call, in addition to everything above. A tool triggered by mistake doesn't get there on its own.

Each rejection says which of the three gates stopped it.

Endpoint authentication

The MCP protocol doesn't come with its own authentication. In http mode, this server requires Authorization: Bearer <MCP_AUTH_TOKEN> on every request, or the secret embedded in the path (/s/<secret>/mcp) for Claude connectors. /healthz is the only public route.

The server refuses to start if MCP_AUTH_TOKEN is missing or shorter than 32 characters. That's intentional: it prevents publishing an open gateway to your Stripe account by accident.

Running locally

pip install -r requirements.txt

# stdio (para Claude Desktop)
STRIPE_API_KEY=rk_test_xxx python stripe_mcp.py

# http (como en Railway)
STRIPE_MCP_TRANSPORT=http \
STRIPE_API_KEY=rk_test_xxx \
MCP_AUTH_TOKEN=$(python3 -c "import secrets;print(secrets.token_urlsafe(48))") \
PORT=8000 python stripe_mcp.py

On startup it prints which mode it ended up in:

[stripe-mcp] streamable-http on 0.0.0.0:8000  mode=test  read_only=True  allow_live_writes=False  writes_enabled=False

Notes on the Stripe API

Things the server already handles for you, and that are good to know when reading responses:

• Stripe doesn't accept JSON in the body. Everything goes application/x-www-form-urlencoded with bracket notation: metadata[order]=6735, expand[]=customer, items[0][price]=price_1. The server translates nested dicts and lists only.

• Money is an integer in the smallest unit. 2500 with usd is $25.00. And there are zero-decimal currencies (JPY, KRW, CLP…) where the integer is the amount — dividing by 100 there would be a mistake. Formatted outputs respect that.

• Test and live are separate universes. An id created in test returns 404 with a live key and vice versa. That's the most common cause of a 404 with a correct id.

• Pagination is cursor-based, not page-based. The last id is taken and passed as starting_after. When there's more, the response includes next_page_hint with the exact value.

• There's no PATCH or PUT. Stripe uses POST for both creating and updating. Only GET, POST, and DELETE.

• Lists don't filter by status on charges or payment_intents. You have to filter over the returned records or use stripe_search.

• stripe_list_subscriptions omits canceled ones by default. For churn questions you have to pass status='all' or the answer comes out wrong silently.

• The search index takes up to a minute to see a newly created object. For new objects, look them up by id.

• Events are only kept for 30 days. For anything older, go to the objects.

• There's no aggregation endpoint. That's why stripe_revenue_summary pages and sums on the MCP server side, and warns with complete=false when the page cap cut off the count — those totals are partial and shouldn't be reported as final.

• Each POST goes out with an Idempotency-Key, so a retry doesn't charge twice. Stripe remembers them for 24 hours.

Security

• Secrets go in environment variables, never in code. The .gitignore blocks .env files.

• Use a restricted key (rk_...), not the secret key. You can create as many as you want in the dashboard and give them per-resource permissions. For this deployment: everything Read, nothing Write. An sk_live_ gives full access to the account, including moving money.

• A single shared token means zero per-person traceability. Anything anyone does is logged as the same key.

• There's no rate limiting of its own. Whoever has the MCP_AUTH_TOKEN can hit Stripe until they run into Stripe's limit (~100 read req/s on live).

• To cut off access at once: delete the restricted key at https://dashboard.stripe.com/apikeys — the server becomes useless instantly.