Stripe MCP server setup for Claude Code and Cursor

Quick answer: The Stripe MCP server is a Node process that wraps the Stripe REST API as MCP tools. Install with one npx command, drop a test-mode secret key in the env block, and Claude Code or Cursor can read customers, create payment links, and pull invoices. Setup takes 4 minutes, tested on server version 0.3.5 against Stripe API version 2024-06-20 on April 15, 2026.

The Stripe MCP server makes your billing data reachable from the editor. Instead of hunting for a customer in the dashboard, the agent looks them up by email and summarizes their subscription history in one turn. Instead of hand-writing a payment link for a one-off invoice, it creates the link for you.

This guide covers installation, config for both editors, working prompt patterns, and the safety rails you want in place before the key ever touches a live account.

What this server does

The server exposes about 30 Stripe endpoints as MCP tools backed by the official stripe Node library. When Claude wants to read a customer, it calls get_customer by ID or email. When it wants to create a payment link, it calls create_payment_link with a price ID and success URL.

Main tool groups:

• Customers: list_customers, get_customer, search_customers, update_customer
• Payments: list_payments, get_payment, refund_payment
• Subscriptions: list_subscriptions, get_subscription, cancel_subscription, pause_subscription
• Invoices: list_invoices, get_invoice, send_invoice
• Payment Links: create_payment_link, list_payment_links
• Catalog: list_products, list_prices, list_coupons
• Balance: get_balance, list_payouts, list_balance_transactions

The server reads the key at spawn time and sends it as a bearer token on every HTTPS request. There is no local state beyond the connection pool.

Installing Stripe MCP

The package is published as stripe-mcp. The npx -y prefix fetches on first launch. Cold start is about 2 seconds and pulls around 3 MB.

Grab a test-mode secret key before you touch any config:

1. Open https://dashboard.stripe.com/test/apikeys while in test mode.
2. Copy the secret key that starts with sk_test_. Do not use the publishable key - it can only create tokens, not read data.
3. Keep the live mode dashboard closed. The key you want today is the one that does not move real money.

For a production setup eventually, create a restricted key with explicit read-only scopes on Customers, Payments, and Subscriptions, and leave write scopes off unless the agent genuinely needs them.

Configuring for Claude Code

Claude Code reads MCP servers from ~/.claude/mcp.json globally or .mcp.json per project. Add a stripe entry:

{
  "mcpServers": {
    "stripe": {
      "command": "npx",
      "args": ["-y", "stripe-mcp"],
      "env": {
        "STRIPE_SECRET_KEY": "sk_test_your_key_here"
      }
    }
  }
}

Restart Claude Code. Run /mcp and you should see the server with about 30 tools. Call list_customers with limit: 5 as a smoke test.

For shared team projects, do not commit the real key. Use a placeholder in .mcp.json and store STRIPE_SECRET_KEY in a shell env var that the config references.

Configuring for Cursor

Cursor reads from ~/.cursor/mcp.json with the same JSON:

{
  "mcpServers": {
    "stripe": {
      "command": "npx",
      "args": ["-y", "stripe-mcp"],
      "env": {
        "STRIPE_SECRET_KEY": "sk_test_your_key_here"
      }
    }
  }
}

Open Cursor settings > MCP and toggle the server on. First call takes about 2 seconds for spawn. API calls run 150 to 350 ms on average, plus whatever network latency exists between your region and Stripe's us-east region.

Example prompts and workflows

Once the server is attached, Stripe acts like a queryable billing database. A few prompts:

• "Find the customer with email alice@acme.com and show her active subscriptions and last 5 invoices."
• "List every subscription that is past due and tell me the outstanding amount total."
• "Create a payment link for 99 USD one-time, with success URL set to our thank-you page."
• "Show me refunds issued in the last 7 days, grouped by reason."
• "Find customers created in the last 30 days who have not made a payment yet."

The model chains calls automatically. A "summarize this customer" flow runs search_customers to resolve the email, list_subscriptions with the customer ID, and list_invoices with the same ID. Three tool calls for a complete profile.

One pattern that saves time: tell the model what date range to use up front. Stripe's created.gte filter is much faster than pulling everything and sorting client-side - for a busy account, the difference is seconds versus minutes.

Troubleshooting

Tool call returns 401. The key is wrong or has been rolled. Regenerate in the dashboard and restart the MCP server.

Tool call returns 400 with a mode error. You are calling a live-mode endpoint with a test key, or vice versa. Check the key prefix - test keys start with sk_test_, live with sk_live_. The server does not auto-detect which mode the prompt wants.

Rate limit error (429). Stripe's default limit is 100 read requests per second and 100 write per second. Bulk agent loops can hit this. Ask the model to batch with list calls that return multiple records per request rather than looping through IDs.

Customer search returns no results. Stripe Search indexes documents asynchronously - a customer created in the last few seconds may not be searchable yet. Fall back to list_customers with an email filter for freshly-created records.

Server fails with ENOENT. npx is not on PATH for the editor. Launch from a terminal or hardcode the npx path.

Alternatives

If the Stripe server does not fit, a few options exist:

• paddle-mcp for teams on Paddle, which handles Merchant of Record billing.
• lemonsqueezy-mcp for the Lemon Squeezy equivalent.
• Direct Stripe CLI through a shell MCP if you need tail logs, trigger events, or manage webhooks.

For read-only reporting workloads, the Stripe Sigma BigQuery export with a BigQuery MCP server can outperform the REST API on large queries. Trade-off is daily freshness instead of real-time.

The Stripe MCP server is the right default for anyone who lives in Stripe during the day. Four minutes of setup plus one restricted key replaces a lot of dashboard clicking. Keep the key in test mode until you trust the prompt patterns, then promote to a tightly-scoped live restricted key.