Connect a module
Stripe
ShopMCP's Stripe integration lets you chat with your Stripe account — customers, payment intents, charges, subscriptions, invoices, products, disputes — using a single restricted API key. Read-only in v1; writes ship in v1.1. Setup takes under 2 minutes.
Why ShopMCP's integration, not Stripe's own MCP
Stripe ships an official MCP server at mcp.stripe.com. It’s great for scaffolding — create a customer, draft a payment link, spin up a subscription — but it’s analytics-thin. You cannot ask it “what’s in tomorrow’s payout?”, “which subscriptions are dying?”, or “which disputes need a response this week?” because the tools simply aren’t there. ShopMCP’s Stripe integration is analytics-first — filtered lists, search-DSL support, aggressive expansions, and payout/balance/reports coverage Stripe’s own MCP doesn’t expose.
| Area | Stripe's official MCP | ShopMCP Stripe | Why it matters |
|---|---|---|---|
| Customers | list + create, no filters | list (date + email filters), get, search (DSL) — all with subscriptions expanded | One call answers 'customers + their plans' instead of N. |
| PaymentIntents | list + create | list (date + customer), get (auto-expand failure reason), search | 'Why did this charge fail?' is one round-trip, not four. |
| Charges (legacy) | Not exposed | list + get + search | Pre-PaymentIntent history + raw fee breakdown. |
| Subscriptions | list + update + cancel | list (status + price filters), get, search (DSL) — no writes in v1 | MRR slicing needs filters and DSL. Their MCP can cancel but not analyse. |
| Invoices / dunning | list + create | list with status + collection_method filters, get, search | 'Past-due + automatic billing' is the dunning queue — filters required. |
| Payouts | Not exposed | list + get + line items (Tier B, next PR) | Biggest single gap in Stripe's MCP. Payout reconciliation lives here. |
| BalanceTransactions | Not exposed | list (Tier B, next PR) | The unified ledger — fees, net, type breakdown. |
| Reports API | Not exposed | report types + run + get run (Tier B, next PR) | Stripe-managed pre-baked reports. Async CSV — essential for finance. |
| Events (audit trail) | Not exposed | list (Tier B, next PR) | Churn cohort analytics + webhook-style auditing. |
| Disputes | list + update (evidence) | list (status + charge filter, auto-expand customer) — evidence drafting in v1.1 | Theirs submits evidence but can't queue disputes by deadline. Ours prioritises. |
| Stripe Search DSL | Not exposed on any resource | Exposed on customers / PIs / charges / subs / invoices | How you express 'past-due invoices > $500 on enterprise plans'. Their absence is why Stripe's MCP can't answer real questions. |
| Refunds | create_refund | list (Tier B, next PR); create in v1.1 with mandatory Idempotency-Key | Refund triage (who, why, how much) needs read surface. Idempotency keys prevent duplicate refunds on retries. |
| Products / Prices | full CRUD | list products + list prices (read-only in v1) | They're ahead on catalog writes; we're read-first. |
| Checkout / Coupons | sessions + payment links + coupons | Deferred to v1.1 | They're ahead on growth-write surface. |
| Connect (platforms) | ~10 tools | Out of scope — not a platform play | Only matters if you're issuing connected accounts. |
| expand[] (N+1 killer) | Not exposed | Aggressive defaults on every list/get | Collapses 4 round-trips into 1 on the common 'why did this fail' path. |
| Idempotency-Key on writes | Not enforced | Required on every v1.1 write | Prevents duplicate refunds / double-cancellations on LLM retries. |
| Live vs test badging | Inferred, not surfaced | Derived from key prefix, badged in UI + tools | Prevents 'oh no, I was pointed at live the whole time' accidents. |
Bottom line:Stripe’s MCP is dev-scaffolding-first. ShopMCP’s is analytics-first. The two happily coexist — use theirs if you want your agent to mint new payment links, use ours to run the business.
Before you start
You need admin access to the Stripe account you want to connect. Restricted keys can only be minted by admins in the Stripe Dashboard. ShopMCP never asks for your publishable key (pk_) or secret key (sk_) — those are too powerful for what we need.
Test vs live mode. Stripe keys are prefixed with rk_live_ or rk_test_. ShopMCP detects this automatically and badges the connection. Connect a test-mode account first if you want to try ShopMCP without touching real money.
Step 1 — Open Stripe Dashboard
In the ShopMCP settings page, click Open Stripe Dashboardin the connect card. We send you to Stripe’s “Create restricted key” page. Stripe starts new restricted keys with every permission set to None, so set the ShopMCP resources below to Read before you create the key.
- Name the key
ShopMCP(auto-populated). - Set these resources to Read: Customers, Charges, PaymentIntents, Subscriptions, Invoices, Products, Prices, Checkout Sessions, Balance, Balance Transaction Sources, Payouts, Refunds, Disputes, Events, Files, Report Runs and Report Types, and Account. Leave every Write permission off.
- Click
Create key. Stripe shows the full key value only once— copy it immediately.
Step 2 — Paste the key into ShopMCP
Back in ShopMCP, paste the key (starts with rk_) into the connect form. Optionally add a label if you plan to connect multiple Stripe accounts (e.g. “EU entity”, “US live”, “Test”). Click Connect Stripe.
We verify the key with a single GET /v1/account round-trip. You get a specific error message if the key is the wrong type (e.g. you pasted a publishable key), missing scopes, or unreachable. The key is encrypted at rest in our DB and never sent to the LLM.
Step 3 — Try it from chat
Open a chat and ask any of these questions — ShopMCP will route to the Stripe tools automatically:
- “Show me customers that signed up in the last 7 days.”
- “Why did payment intent pi_abc123 fail?”
- “List subscriptions that are past due.”
- “What’s our MRR by plan?”
- “Which disputes need a response this week?”
- “Summarise refunds over $100 from the last 30 days.”
Rotating keys
If you need to rotate the key (employee departure, suspected leak), do it in Stripe Dashboard first — revoke the old key, mint a new one. Then come back to ShopMCP, disconnect the existing connection, and add the new key. Chat sessions mid-flight fall back to the next tools/list refresh (45 seconds) to pick up the new credentials.
What v1 does not yet do
- Writes.Refunds, subscription cancels, dispute evidence submission land in v1.1. For now ShopMCP can show you exactly what needs to happen — you take the action in the Stripe Dashboard.
- Balance / payouts / reports. Ship in the next PR (Tier B). These are the differentiated tools behind the payout reconciliation and MRR health playbooks.
- Radar / fraud reviews. Planned for v1.1.
- Coupons / promotion codes / billing portal / subscription schedules. Planned for v1.1.
Troubleshooting
“That’s a secret key” / “That’s a publishable key”. ShopMCP rejects sk_ and pk_ keys by design. Use the restricted key link from the connect form and set the listed ShopMCP resources to Read in Stripe.
“Missing the account:read scope”. Rare — happens when you mint a key without the default account:read scope. Re-mint the key and set Account to Read.
Need more help? See Stripe’s own docs on restricted keys or file an issue at github.com/shopmcp/shopmcp/issues.