Stripe MCP — 사용 사례, 설치 & 라이브 데모

Name: Stripe MCP Server
Author: stripe

왜 쓰나요

핵심 기능

Stripe 핵심 리소스 전반에 걸쳐 읽기 및 쓰기
API 키를 통한 테스트 모드 및 라이브 모드 전환
강력한 검색(stripe.search 스타일 쿼리)
--tools= CLI 인수를 통한 도구 선택 — 안전을 위해 읽기 전용으로 제한
Stripe에서 직접 유지 관리

라이브 데모

실제 사용 모습

stripe.replay ▶ 준비됨

0/0

설치

클라이언트 선택

~/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"
      ]
    }
  }
}

Claude Desktop → Settings → Developer → Edit Config 열기. 저장 후 앱 재시작.

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

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

Cursor는 Claude Desktop과 동일한 mcpServers 스키마 사용. 프로젝트 설정이 전역보다 우선.

VS Code → Cline → MCP Servers → Edit

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

Cline 사이드바의 MCP Servers 아이콘 클릭 후 "Edit Configuration" 선택.

~/.codeium/windsurf/mcp_config.json

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

Claude Desktop과 같은 형식. Windsurf 재시작 후 적용.

~/.continue/config.json

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

Continue는 맵이 아닌 서버 오브젝트 배열 사용.

~/.config/zed/settings.json

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

context_servers에 추가. 저장 시 Zed가 핫 리로드.

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

한 줄 명령. claude mcp list로 확인, claude mcp remove로 제거.

사용 사례

실전 활용법: Stripe

고객의 청구가 실패하는 이유 조사

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

언제 쓸까: Customer says 'my card was declined 3 times'. You want to see what actually happened on Stripe's side.

사전 조건

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

흐름

Find the customer

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

→ 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.✓ 복사됨

→ 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').✓ 복사됨

→ Clear customer-facing explanation

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

함정

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

언제 쓸까: You agreed a one-off custom price with a customer and need an invoice or payment link, fast.

사전 조건

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

흐름

Find or create the customer

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

→ 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.✓ 복사됨

→ 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.✓ 복사됨

→ URL + summary; no surprise emails sent

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

함정

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

함께 쓰기: supabase

Compute current MRR and churn from Stripe subscriptions

👤 Founders doing finance ops ⏱ ~15 min intermediate

언제 쓸까: Monthly review; you want a quick MRR/churn read straight from source.

흐름

Pull active subscriptions

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

→ 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.✓ 복사됨

→ 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.✓ 복사됨

→ Single number with calculation breakdown

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

함정

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

함께 쓰기: filesystem

Process a refund with appropriate guardrails

👤 Support leads with refund authority ⏱ ~5 min beginner

언제 쓸까: Customer requests a refund; you want to verify the charge and process it cleanly.

사전 조건

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

흐름

Find and validate the charge

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

→ 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.✓ 복사됨

→ Dry-run preview of API call
Execute on confirmation

Proceed with the partial refund. Return the refund ID and updated charge state.✓ 복사됨

→ Refund created, charge marked partially_refunded

결과: Refund processed cleanly with audit trail.

함정

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

언제 쓸까: End of quarter, you want to know exactly what's in Stripe and what's about to land in the bank.

흐름

Get current balance breakdown

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

→ 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.✓ 복사됨

→ 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.✓ 복사됨

→ Aggregated period total + near-term forecast

결과: A reconciliation-ready summary.

함정

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

함께 쓰기: filesystem

조합

다른 MCP와 조합해 10배 효율

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.✓ 복사됨

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.✓ 복사됨

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.✓ 복사됨

도구

이 MCP가 노출하는 것

도구	입력	언제 호출	비용
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

비용 및 제한

운영 비용

API 쿼터: Stripe API has generous rate limits (100 req/s read in live, 25 req/s in test by default)
호출당 토큰: Stripe objects are token-heavy (rich nested data). Use expand only when needed; cap list sizes
금액: MCP free; Stripe charges per processed payment, not per API call
팁: 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.

보안

권한, 시크릿, 파급범위

최소 스코프: restricted key with the minimum scopes per workflow (e.g. Customers:read + Charges:read for support)

자격 증명 저장: API key in env var STRIPE_SECRET_KEY. Never commit. Use restricted keys, not the root secret key.

데이터 외부 송신: All calls to api.stripe.com (TLS, PCI-handled by Stripe)

절대 부여 금지: 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.

문제 해결

자주 발생하는 오류와 해결

401 Invalid API Key

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

확인: 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.

대안

Stripe 다른 것과 비교

대안	언제 쓰나	단점/장점
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

Stripe

왜 쓰나요

핵심 기능

라이브 데모

실제 사용 모습

설치

클라이언트 선택

사용 사례

실전 활용법: Stripe

사전 조건

흐름

함정

사전 조건

흐름

함정

흐름

함정

사전 조건

흐름

함정

흐름

함정

조합

다른 MCP와 조합해 10배 효율

도구

이 MCP가 노출하는 것

비용 및 제한

운영 비용

보안

권한, 시크릿, 파급범위

문제 해결

자주 발생하는 오류와 해결

대안

Stripe 다른 것과 비교

더 보기

리소스