mcp-stripe

Stripe MCP 取引スキル

Stripe MCP サーバーを介して取引操作を実行します。

ファイルベースのパイプライン（パスのみを受け渡す）

複数ステップのワークフローに請求処理を組み込む場合は、すべてのコンテキストと成果物をディスクに保存し、エージェント／サブエージェント間ではパスのみを受け渡します。

推奨ディレクトリ構造（プロジェクト内）：runs/<workflow>/active/<run_id>/

• 入力：01-input/goal.md（要件）、01-input/context.json（既知の顧客／請求書／サブスクリプション／payment_intent の ID など）
• 計画：03-plans/stripe-actions.md（実行する操作の一覧。金銭や契約に関する内容はここに記載し、まず確認を待ちます）
• 出力：05-final/receipt.md ＋ 05-final/receipt.json（オブジェクトの種類＋ID＋主要フィールド＋次の手順）
• ログ：logs/events.jsonl（各ツール呼び出しの概要。機密情報をそのまま記録しないでください）

接続設定

MCP サーバー：https://mcp.stripe.com

Claude Code 接続：

claude mcp add --transport http stripe https://mcp.stripe.com/
claude /mcp  # authenticate

認証：OAuth を推奨します。API キーが必要な場合は、制限付きキーを Bearer トークンとして使用してください。

モード：デフォルトではテストモードです。ライブモードへの切り替えには、ユーザーが明示的に「live」と伝えたうえで、二重確認が必要です。

3 つの厳守事項

1. 書き込み前に読み取る - 顧客／商品／価格を作成する前に、まず list_* または search_stripe_resources を使用して、すでに存在するか確認し、オブジェクトの重複を避けてください
2. 金銭や契約に関する操作には確認が必要 - create_refund、cancel_subscription、update_subscription、update_dispute は、実行前に内容を表示し、ユーザーから明示的な確認を得てください
3. 迷ったら検索する - オブジェクト ID、フィールド、または方法が不確かな場合は、パラメーターを推測せず、まず search_stripe_documentation または search_stripe_resources を呼び出してください

利用可能なツール

カテゴリ	ツール	説明
アカウント	get_stripe_account_info	アカウント情報を取得
残高	retrieve_balance	利用可能な残高／保留中の残高を照会
顧客	create_customer、list_customers	顧客を作成／一覧表示
商品	create_product、list_products	商品を作成／一覧表示
価格	create_price、list_prices	価格を作成／一覧表示
請求書	create_invoice、create_invoice_item、finalize_invoice、list_invoices	請求書の一連のワークフロー
支払いリンク	create_payment_link	共有可能な支払いリンクを作成
Payment Intent	list_payment_intents	Payment Intent を一覧表示（照会のみ）
返金	create_refund	⚠️ 危険な操作 - 確認が必要
異議申し立て	list_disputes、update_dispute	⚠️ 更新には確認が必要
サブスクリプション	list_subscriptions、update_subscription、cancel_subscription	⚠️ 更新／キャンセルには確認が必要
クーポン	create_coupon、list_coupons	クーポンを作成／一覧表示
検索	search_stripe_resources、fetch_stripe_resources、search_stripe_documentation	オブジェクト／ドキュメントを検索

できないこと（ツール一覧にない操作）：

• ❌ PaymentIntent／請求を直接作成する
• ❌ サブスクリプションを作成する（create_subscription）
• ❌ プロモーションコードを作成する（クーポンのみ）
• ❌ オブジェクトを削除する

危険な操作の処理フロー

create_refund、cancel_subscription、update_subscription、update_dispute を実行する前に：

1. 最初に表示する - 操作対象のオブジェクト ID と主要フィールドを一覧表示します
2. 影響を説明する - 返金額／キャンセル日時／変更内容を説明します
3. 確認を求める - ユーザーが「confirm」／「yes」／「proceed」と明示的に返信するまで待ちます
4. 実行して領収情報を返す - 操作結果＋オブジェクト ID＋ステータスを返します

確認プロンプトの例：

About to execute refund:
- PaymentIntent: pi_xxx
- Amount: £50.00 (full amount)
- Reason: requested_by_customer

Reply "confirm" to proceed, or "cancel" to abort.

デフォルト設定

• 通貨：ユーザーが指定した通貨を優先します。指定がない場合は既存オブジェクト（Price／Invoice／PaymentIntent）の通貨を使用します。それでも不明な場合は確認してください
• 金額：小数での入力を受け付け、最小通貨単位の整数に自動変換します（例：£19.99 → 1999）
• 領収情報の出力：オブジェクトの種類＋ID＋主要フィールド＋次の手順

よくあるワークフロー

顧客を作成

1. search_stripe_resources or list_customers to check if already exists
2. If not exists, create_customer(name, email, metadata)
3. Return cus_xxx + key info

商品と価格を作成

1. list_products to check if product already exists
2. create_product(name, description)
3. create_price(product=prod_xxx, unit_amount=amount in smallest unit, currency="gbp", recurring if needed)
4. Return prod_xxx + price_xxx

請求書の作成と送信

1. Confirm customer ID (if unknown, query with list_customers)
2. create_invoice(customer=cus_xxx, collection_method, days_until_due)
3. create_invoice_item(invoice=inv_xxx, price=price_xxx, quantity)
4. finalize_invoice(invoice=inv_xxx)
5. Return inv_xxx + hosted_invoice_url

支払いリンクの作成

1. Confirm price ID (if unknown, query with list_prices)
2. create_payment_link(line_items=[{price, quantity}], after_completion if needed)
3. Return payment link URL

返金（危険）

1. list_payment_intents to find target payment
2. Display pi_xxx + amount + customer info
3. Request user confirmation
4. After confirmation, create_refund(payment_intent=pi_xxx, amount for partial refund, reason)
5. Return re_xxx + status

サブスクリプションのキャンセル（危険）

1. list_subscriptions(customer=cus_xxx) to find target
2. Display sub_xxx + current status + next billing date
3. Ask: cancel immediately or at period end (cancel_at_period_end)
4. After confirmation, cancel_subscription(subscription=sub_xxx)
5. Return cancellation result

ツールのパラメーターの詳細

tools.md を参照してください。

エラー処理

• オブジェクトが存在しません：正しい ID を見つけるには、search_stripe_resources または fetch_stripe_resources を使用してください
• パラメーターエラー：正しいパラメーター形式を確認するには、search_stripe_documentation を使用してください
• 権限が不十分です：API キーの権限スコープを確認するようユーザーに依頼してください
• ネットワークエラー：再試行するか、MCP 接続の状態を確認するよう提案してください