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 | Biggest single gap in Stripe's MCP. Payout reconciliation lives here. |
| BalanceTransactions | Not exposed | list | The unified ledger — fees, net, type breakdown. |
| Reports API | Not exposed | report types + run + get run | Stripe-managed pre-baked reports. Async CSV — essential for finance. |
| Events (audit trail) | Not exposed | list | 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; 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 dashboard rows to Read: Balance, Balance Transaction Sources, Charges and Refunds, Customers, Events, Files, Payment Disputes, Payment Intents, Payment Methods, Payouts, Products, Sources, Invoices, Prices, Subscriptions, and Financial Reports. If Stripe shows
Accounts v2, set that to Read too so ShopMCP can label the connection with account metadata. 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.
ShopMCP’s required verification call is GET /v1/balance. After that, ShopMCP tries GET /v1/account only to pull a nicer account label. If Stripe blocks that account-metadata read, the connection still saves and you can rename it in ShopMCP. You get a specific error message if the key is the wrong type, 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.
- 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 balance:read scope”. Re-mint the key and set Balance to Read. Balance access is the minimum verification scope ShopMCP requires before saving a Stripe connection.
The account label looks generic. Stripe blocked the optional account-metadata read. Re-mint with Accounts v2 set to Read, or keep the connection as-is and rename it in ShopMCP.
Need more help? See Stripe’s own docs on restricted keys or file an issue at github.com/shopmcp/shopmcp/issues.