Stripe MCP Server

Stripe の API を Claude に公開する MCP（Model Context Protocol）サーバー。 Railway に 読み取り専用モード でデプロイすることを想定しています。

👉 デプロイ手順は DEPLOY-RAILWAY.md にあります。

機能

Claude に Stripe を照会するための 17 のツールを提供します。顧客、請求、支払い、 サブスクリプション、請求書、カタログ、残高、取引、ペイアウト、イベント、 紛争 — さらに、任意のエンドポイントに到達する汎用ツール、任意のオブジェクトを ID で解決するツール、および収益の集計レポートも含まれます。

Related MCP server: Stripe MCP

環境変数

書き込みの三重のゲート

Stripe は実際の資金を動かします。誤った POST は顧客への返金、サブスクリプションのキャンセル、またはレコードの完全な削除につながります。そのため、独立した 3 つのロックがあり、書き込みはそのすべてを通過する必要があります。

1. STRIPE_READ_ONLY — デフォルトはトランスポートに依存

• stdio（ローカル）: デフォルトで書き込み 許可。信頼できる単一ユーザーが自分のマシンで使用。

• http（リモート）: デフォルトで書き込み ブロック。有効にするには意図的に STRIPE_READ_ONLY=0 を設定する必要があります。

公開デプロイで変数を忘れると、読み取り専用のままになり、開放されません。

2. STRIPE_ALLOW_LIVE_WRITES — ライブモードのゲート

読み取り専用をオフにしても、ライブ キーは STRIPE_ALLOW_LIVE_WRITES=1 を設定するまで書き込みを拒否し続けます。テストキー（sk_test_、rk_test_）はこのゲートを通過しません。テストデータでの実験に儀式は必要ありません。

3. confirm=true — エンドポイントごとのゲート

破壊的なエンドポイント（/v1/refunds、/v1/payouts、/v1/transfers、 サブスクリプションのキャンセル、顧客の削除、紛争のクローズ）は、上記すべてに加えて、呼び出しに confirm=true を要求します。誤って起動されたツールは、単独ではそこに到達できません。

各拒否は、どの 3 つのゲートがそれを停止したかを示します。

エンドポイントの認証

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 はボディに JSON を受け付けません。 すべて application/x-www-form-urlencoded で、ブラケット表記を使用します: metadata[order]=6735、expand[]=customer、 items[0][price]=price_1。サーバーはネストされた dict とリストのみを変換します。

• 金額は最小単位の整数です。 2500 と usd は $25.00 です。 また、ゼロ小数の通貨（JPY、KRW、CLP など）では、整数がそのまま金額になります。 そこで 100 で割るのは誤りです。フォーマットされた出力はこれを尊重します。

• テストとライブは別々の世界です。 テストで作成された ID はライブキーで 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 はデフォルトでキャンセル済みを省略します。 チャーンに関する質問には status='all' を渡す必要があります。そうしないと、レスポンスが静かに間違ったものになります。

• 検索インデックスは、新しく作成されたオブジェクトを認識するまで最大 1 分かかります。 新しいオブジェクトの場合は、ID で検索してください。

• イベントは 30 日間のみ保存されます。 それより前のものはオブジェクトにアクセスする必要があります。

• 集計エンドポイントはありません。 そのため、stripe_revenue_summary は MCP サーバー側でページングして合計し、ページ上限でカウントが途切れた場合は complete=false で通知します。これらの合計は部分的なものであり、最終的なものとして報告してはなりません。

• 各 POST には Idempotency-Key が付与されるため、再試行しても二重請求されません。Stripe はこれらを 24 時間記憶します。

セキュリティ

• シークレットは環境変数に保存され、コードには決して保存されません。.gitignore は .env ファイルをブロックします。

• シークレットキーではなく、制限付きキー（rk_...）を使用してください。 ダッシュボードで何度でも作成でき、リソースごとに権限を付与できます。このデプロイでは、すべて 読み取り、書き込み はなし。sk_live_ は、資金の移動を含むアカウントへの完全なアクセスを提供します。

• 共有トークンが 1 つだけの場合、個人単位のトレーサビリティはゼロです。誰かが行ったすべての操作は、同じキーとして記録されます。

• 独自のレート制限はありません。MCP_AUTH_TOKEN を持っている人は、Stripe の制限（ライブでの読み取りで約 100 req/s）に達するまで Stripe にアクセスできます。

• アクセスを即座に遮断するには、https://dashboard.stripe.com/apikeys で制限付きキーを削除します。サーバーは即座に使用不能になります。