Stripe MCP — Use Cases, Install & Live Demo

Name: Stripe MCP Server
Author: stripe

Why use it

Key features

Read and write across Stripe core resources
Test-mode and live-mode toggling via API key
Powerful search (stripe.search-style queries)
Tool selection via --tools= CLI arg — restrict to read-only for safety
Maintained directly by Stripe

Live Demo

What it looks like in practice

stripe.replay ▶ ready

0/0

Install

Pick your client

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "stripe": {
      "command": "npx",
      "args": [
        "-y",
        "@stripe/mcp",
        "--tools=all"
      ]
    }
  }
}

Open Claude Desktop → Settings → Developer → Edit Config. Restart after saving.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "stripe": {
      "command": "npx",
      "args": [
        "-y",
        "@stripe/mcp",
        "--tools=all"
      ]
    }
  }
}

Cursor uses the same mcpServers schema as Claude Desktop. Project config wins over global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "stripe": {
      "command": "npx",
      "args": [
        "-y",
        "@stripe/mcp",
        "--tools=all"
      ]
    }
  }
}

Click the MCP Servers icon in the Cline sidebar, then "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "stripe": {
      "command": "npx",
      "args": [
        "-y",
        "@stripe/mcp",
        "--tools=all"
      ]
    }
  }
}

Same shape as Claude Desktop. Restart Windsurf to pick up changes.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "stripe",
      "command": "npx",
      "args": [
        "-y",
        "@stripe/mcp",
        "--tools=all"
      ]
    }
  ]
}

Continue uses an array of server objects rather than a map.

~/.config/zed/settings.json

{
  "context_servers": {
    "stripe": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "@stripe/mcp",
          "--tools=all"
        ]
      }
    }
  }
}

Add to context_servers. Zed hot-reloads on save.

claude mcp add stripe -- npx -y @stripe/mcp --tools=all

One-liner. Verify with claude mcp list. Remove with claude mcp remove.

Use Cases

Real-world ways to use Stripe

Investigate why a customer's charges are failing

👤 Support engineers, founders doing first-line ⏱ ~10 min beginner

When to use: Customer says 'my card was declined 3 times'. You want to see what actually happened on Stripe's side.

Prerequisites

Stripe restricted API key with read on charges/customers — dashboard.stripe.com/apikeys → Restricted keys → grant Read on Customers, Charges, Payment intents

Flow

Find the customer

Find the Stripe customer with email '[email protected]'. Show their default payment method and total spend.✓ Copied

→ Customer record with payment method details
Pull recent failed charges

List this customer's charges in the last 30 days where status != 'succeeded'. For each, show the failure code and message.✓ Copied

→ Failure list with card_declined/expired_card/etc. codes
Explain and recommend action

What's the actual issue? Recommend what to tell the customer (e.g., 'card expired — please update', or 'fraud block — try a different card').✓ Copied

→ Clear customer-facing explanation

Outcome: Resolved support ticket with the actual cause, not 'try again later'.

Pitfalls

Looking at charges only — misses Payment Intents that never made it to a charge — Also check Payment Intents with status 'requires_payment_method' or 'canceled'
Customer says 'declined' but it was 3DS abandonment — 3DS challenges that the user closes show as requires_action then expire; check timeline

Create a test invoice and payment link for a deal

👤 Sales and ops people closing custom deals ⏱ ~5 min beginner

When to use: You agreed a one-off custom price with a customer and need an invoice or payment link, fast.

Prerequisites

TEST mode key (sk_test_...) — Always start in test mode. Switch to live key only after the flow is validated.

Flow

Find or create the customer

Look up Stripe customer with email '[email protected]'. If none, create one with name 'BigCo Inc'.✓ Copied

→ Customer ID returned
Create a one-off price + invoice item

Create a one-off invoice item: $4,500, description 'Q2 onboarding services'. Attach to that customer. Then create and finalize an invoice.✓ Copied

→ Invoice with hosted_invoice_url
Confirm deliverable

Give me the hosted invoice URL and a summary of what was created. Don't email it — I'll forward manually.✓ Copied

→ URL + summary; no surprise emails sent

Outcome: An invoice you can send to the customer in 90 seconds.

Pitfalls

Auto-emailing customers from chat is a footgun — Use auto_advance: false and skip send_invoice until you've reviewed; the MCP shouldn't email production customers without explicit confirmation
Test/live mode mix-up means real money flows for a 'test' — Always inspect the API key prefix (sk_test_ vs sk_live_) before any mutation; have the MCP echo it back

Combine with: supabase

Compute current MRR and churn from Stripe subscriptions

👤 Founders doing finance ops ⏱ ~15 min intermediate

When to use: Monthly review; you want a quick MRR/churn read straight from source.

Flow

Pull active subscriptions

List all active Stripe subscriptions (status='active' or 'trialing'). Group by price_id, sum the MRR-equivalent.✓ Copied

→ Per-price totals + grand total
Pull canceled-this-month

List subscriptions canceled in the last 30 days. For each, show the start date, MRR contributed, and customer.✓ Copied

→ Churn list with revenue impact
Compute net new MRR

Net new MRR = new this month - churn this month. Compute and write a 3-line summary.✓ Copied

→ Single number with calculation breakdown

Outcome: An accurate MRR snapshot you can paste into your monthly review.

Pitfalls

Annual plans need monthly normalization — Divide annual price by 12 when summing MRR; the MCP doesn't do this for you
Discounts and credits skew gross vs net — Decide MRR convention (gross vs net of discounts) and apply it consistently

Combine with: filesystem

Process a refund with appropriate guardrails

👤 Support leads with refund authority ⏱ ~5 min beginner

When to use: Customer requests a refund; you want to verify the charge and process it cleanly.

Prerequisites

API key with refunds:write — Restricted key, grant only the minimum scopes

Flow

Find and validate the charge

Find Stripe charge ch_xxx. Show amount, customer, status, and whether it's already refunded (partial or full).✓ Copied

→ Charge details + refund history
Preview the refund

I want to refund $50 of $200 (partial). Show me what the refund call would look like. Don't execute yet.✓ Copied

→ Dry-run preview of API call
Execute on confirmation

Proceed with the partial refund. Return the refund ID and updated charge state.✓ Copied

→ Refund created, charge marked partially_refunded

Outcome: Refund processed cleanly with audit trail.

Pitfalls

Refunding more than original charge fails confusingly — Always check the remaining refundable balance before requesting; the MCP echoes the limit
Refund triggers webhook to your app — may double-update internal state — Coordinate refund flow with whoever maintains the webhook handler

Audit balance and recent payouts before quarter close

👤 Finance, founders ⏱ ~10 min intermediate

When to use: End of quarter, you want to know exactly what's in Stripe and what's about to land in the bank.

Flow

Get current balance breakdown

Show current Stripe balance: available, pending, in-transit. Break down by currency.✓ Copied

→ Per-currency balance triple
List recent payouts

List payouts in the last 90 days with date, amount, status, and arrival date. Sort by date desc.✓ Copied

→ Payout schedule with totals
Reconcile to your books

What's the total payout amount in the period? Tell me what to expect to land in the bank in the next 7 days.✓ Copied

→ Aggregated period total + near-term forecast

Outcome: A reconciliation-ready summary.

Pitfalls

Reserves and disputed funds aren't in 'available' — Don't equate balance.available + balance.pending = total cash; check for held balances separately

Combine with: filesystem

Combinations

Pair with other MCPs for X10 leverage

stripe + supabase

Stripe webhook → Supabase Edge Function → Stripe MCP queries to enrich event handling

When Stripe webhook 'invoice.payment_failed' fires, the Edge Function calls Stripe MCP to fetch the customer's recent charges and pastes a summary into our Slack ops channel.✓ Copied

stripe + postgres

Reconcile Stripe charges with your internal orders DB

For each successful Stripe charge yesterday, find the matching row in our orders table by stripe_payment_intent_id. Flag mismatches.✓ Copied

stripe + filesystem

Export Stripe data to CSV for finance team

Export all invoices from last quarter to /reports/invoices-Q1-2026.csv with customer email, amount, status, and date.✓ Copied

Tools

What this MCP exposes

Tool	Inputs	When to call	Cost
list_customers / retrieve_customer / create_customer / update_customer	Stripe customer params	Customer CRUD	free Stripe API
list_products / create_product / update_product	product params	Product catalog ops	free
list_prices / create_price	price params	Price ops (one-off or recurring)	free
list_invoices / create_invoice / finalize_invoice / pay_invoice	invoice params	Invoice lifecycle	free
create_invoice_item	customer, amount, currency, description	Add a line to a draft invoice	free
list_payment_intents / retrieve_payment_intent	PI params	Inspect payment flow state	free
list_charges / retrieve_charge	charge params	Charge inspection	free
create_refund	charge: str, amount?: int	Issue a full or partial refund — destructive in live mode	free Stripe API; refund itself moves money
create_payment_link	line_items, after_completion?	Generate a hosted payment URL to send to a customer	free
list_subscriptions / cancel_subscription / update_subscription	subscription params	Subscription lifecycle	free
retrieve_balance	none	Current available/pending balance	free
list_payouts	limit, created?	See recent and upcoming payouts	free
search_*	query: str (Stripe Search syntax)	Powerful filtering across resources via Search API	free

Cost & Limits

What this costs to run

API quota: Stripe API has generous rate limits (100 req/s read in live, 25 req/s in test by default)
Tokens per call: Stripe objects are token-heavy (rich nested data). Use expand only when needed; cap list sizes
Monetary: MCP free; Stripe charges per processed payment, not per API call
Tip: In test mode, costs are zero. In live mode, the only 'cost' that matters is accidentally-issued refunds or invoices — gate writes with --tools= filtering.

Security

Permissions, secrets, blast radius

Minimum scopes: restricted key with the minimum scopes per workflow (e.g. Customers:read + Charges:read for support)

Credential storage: API key in env var STRIPE_SECRET_KEY. Never commit. Use restricted keys, not the root secret key.

Data egress: All calls to api.stripe.com (TLS, PCI-handled by Stripe)

Never grant: root secret key to long-running agents API key with Refunds:write or Subscriptions:write to autonomous workflows without HITL

Live mode means real money. Always confirm key prefix (sk_live_ vs sk_test_) before any write call.
Use --tools= CLI flag (e.g. --tools=customers.read,charges.read) to restrict the MCP to a safe subset.
Webhooks update internal state — coordinate refunds and cancellations with engineering.

Troubleshooting

Common errors and fixes

401 Invalid API Key

Key wrong, revoked, or test/live mismatch. Verify in dashboard. Confirm env var is exported into the MCP client process.

Verify: curl https://api.stripe.com/v1/balance -u $STRIPE_SECRET_KEY:

Permission denied: this key has no access to ...

Restricted key missing the relevant scope. Edit the key in dashboard to grant the needed permission.

Refund: amount exceeds remaining refundable

Charge already partially refunded. Retrieve the charge first, check amount_refunded, refund only the remainder.

Search returns 0 results despite the object existing

Stripe Search has a propagation delay (~1 minute for newly-created objects). Use list/retrieve for very recent items.

Alternatives

Stripe vs others

Alternative	When to use it instead	Tradeoff
Stripe CLI via shell	You want webhook forwarding, fixture generation, or local testing flows	No agent ergonomics; meant for dev workflows
Direct REST API via fetch MCP	You need a feature the official MCP doesn't expose	Auth, pagination, and types are all manual; way more error-prone

More

Resources

📖 Read the official README on GitHub

🐙 Browse open issues

🔍 Browse all 400+ MCP servers and Skills