Stripe MCP 서버

Stripe API를 Claude에 노출하는 MCP(Model Context Protocol) 서버입니다. Railway에 읽기 전용 모드로 배포하도록 설계되었습니다.

👉 배포 단계는 DEPLOY-RAILWAY.md에 있습니다.

기능

Claude에게 Stripe를 조회할 수 있는 17가지 도구를 제공합니다: 고객, 결제, 지불, 구독, 청구서, 카탈로그, 잔액, 거래, payouts, 이벤트 및 분쟁 — 여기에 더해 모든 엔드포인트에 도달할 수 있는 범용 도구, ID로 모든 객체를 해석하는 도구, 그리고 집계된 수익 보고서가 포함됩니다.

Related MCP server: Stripe MCP

환경 변수

세 가지 쓰기 관문

Stripe는 실제 돈을 움직입니다: 잘못된 POST 하나가 고객에게 환불을 하거나, 구독을 취소하거나, 기록을 영구히 삭제할 수 있습니다. 그래서 독립적인 자물쇠 세 개가 있고, 쓰기는 세 개를 모두 통과해야 합니다.

1. STRIPE_READ_ONLY — 기본값은 전송 방식에 따라 다름

• stdio(로컬): 기본적으로 쓰기 허용. 신뢰할 수 있는 단일 사용자가 자신의 머신에서 사용.

• http(원격): 기본적으로 쓰기 차단. 의도적으로 STRIPE_READ_ONLY=0을 설정해야만 활성화됩니다.

공개 배포에서 변수를 잊어버리면 열린 상태가 아니라 읽기 전용으로 남습니다.

2. STRIPE_ALLOW_LIVE_WRITES — live 모드 관문

읽기 전용을 꺼도 live 키는 STRIPE_ALLOW_LIVE_WRITES=1을 설정하기 전까지 쓰기를 계속 거부합니다. 테스트 키(sk_test_, rk_test_)는 이 관문을 거치지 않습니다: 테스트 데이터로 실험하는 데 의식적인 절차가 필요해서는 안 됩니다.

3. confirm=true — 엔드포인트 관문

파괴적인 엔드포인트(/v1/refunds, /v1/payouts, /v1/transfers, 구독 취소, 고객 삭제, 분쟁 종료)는 위의 모든 조건 외에도 호출 시 confirm=true를 요구합니다. 실수로 트리거된 도구는 혼자서 거기 도달할 수 없습니다.

각 거부는 세 관문 중 어느 것이 막았는지 알려줍니다.

엔드포인트 인증

MCP 프로토콜에는 자체 인증이 없습니다. http 모드에서 이 서버는 모든 요청에 Authorization: Bearer <MCP_AUTH_TOKEN>을 요구하거나, Claude 커넥터용으로 경로에 내장된 비밀(/s/<비밀>/mcp)을 요구합니다. /healthz만 유일한 공개 경로입니다.

서버는 MCP_AUTH_TOKEN이 없거나 32자 미만이면 시작을 거부합니다. 의도적인 설계입니다: 부주의로 Stripe 계정에 열린 게이트웨이를 공개하는 것을 방지합니다.

로컬에서 실행

pip install -r requirements.txt

# stdio (para Claude Desktop)
STRIPE_API_KEY=rk_test_xxx python stripe_mcp.py

# http (como en Railway)
STRIPE_MCP_TRANSPORT=http \
STRIPE_API_KEY=rk_test_xxx \
MCP_AUTH_TOKEN=$(python3 -c "import secrets;print(secrets.token_urlsafe(48))") \
PORT=8000 python stripe_mcp.py

시작 시 어떤 모드로 실행되었는지 출력합니다:

[stripe-mcp] streamable-http on 0.0.0.0:8000  mode=test  read_only=True  allow_live_writes=False  writes_enabled=False

Stripe API 참고 사항

서버가 이미 처리해 주는 것들이며, 응답을 읽을 때 알아두면 좋은 사항입니다:

• Stripe는 body에 JSON을 허용하지 않습니다. 모든 것이 application/x-www-form-urlencoded 형식에 대괄호 표기법을 사용합니다: metadata[order]=6735, expand[]=customer, items[0][price]=price_1. 서버는 중첩된 dict와 list만 변환합니다.

• 금액은 최소 단위의 정수입니다. usd에서 2500은 $25.00입니다. 그리고 소수점이 없는 통화(JPY, KRW, CLP...)도 있는데, 이 경우 정수 자체가 금액입니다 — 여기서 100으로 나누면 오류입니다. 포맷된 출력은 이를 존중합니다.

• 테스트와 live는 분리된 세계입니다. 테스트에서 만든 ID는 live 키로 404를 반환하며 그 반대도 마찬가지입니다. 올바른 ID로 404가 나는 가장 흔한 원인입니다.

• 페이지네이션은 페이지가 아닌 커서 기반입니다. 마지막 ID를 가져와 starting_after로 전달합니다. 더 많은 데이터가 있을 때 응답에는 next_page_hint에 정확한 값이 포함됩니다.

• PATCH나 PUT이 없습니다. Stripe는 생성과 업데이트 모두 POST를 사용합니다. GET, POST, DELETE만 있습니다.

• 목록은 charges와 payment_intents에서 status로 필터링하지 않습니다. 반환된 레코드에서 필터링하거나 stripe_search를 사용해야 합니다.

• stripe_list_subscriptions는 기본적으로 취소된 항목을 생략합니다. churn 관련 질문은 status='all'을 전달해야 합니다. 그렇지 않으면 조용히 잘못된 응답이 나옵니다.

• 검색 인덱스는 새로 생성된 객체를 반영하는 데 최대 1분이 걸립니다. 새 객체는 ID로 검색하세요.

• 이벤트는 30일만 보관됩니다. 그 이전은 객체에서 확인해야 합니다.

• 집계 엔드포인트가 없습니다. 그래서 stripe_revenue_summary가 MCP 서버 쪽에서 페이지네이션하며 합산하고, 페이지 상한이 카운트를 끊으면 complete=false로 알립니다 — 그 합계는 부분적이므로 최종 수치로 보고해서는 안 됩니다.

• 모든 POST는 Idempotency-Key와 함께 나가므로 재시도해도 두 번 청구되지 않습니다. Stripe는 이를 24시간 동안 기억합니다.

보안

• 비밀은 코드가 아닌 환경 변수에 넣습니다. .gitignore가 .env 파일을 차단합니다.

• secret key가 아닌 restricted key(rk_...)를 사용하세요. 대시보드에서 원하는 만큼 만들 수 있고 리소스별 권한을 부여할 수 있습니다. 이 배포의 경우: 모든 항목 읽기, 쓰기 없음. sk_live_는 돈 이동을 포함해 계정에 대한 전체 액세스를 제공합니다.

• 공유 토큰 하나는 사람별 추적성이 전혀 없음을 의미합니다. 누가 무엇을 하든 동일한 키로 기록됩니다.

• 자체 rate limiting이 없습니다. MCP_AUTH_TOKEN을 가진 사람은 Stripe의 한도(live에서 읽기 약 100 req/s)에 부딪힐 때까지 Stripe에 요청할 수 있습니다.

• 액세스를 즉시 차단하려면 https://dashboard.stripe.com/apikeys에서 restricted key를 삭제하세요 — 서버는 즉시 무용지물이 됩니다.