mcp-stripe

Stripe MCP 交易技能

通过 Stripe MCP 服务执行交易操作。

基于文件的工作流（仅传递路径）

将账单操作集成到多步骤工作流时，请将所有上下文和产物保存到磁盘，并在 Agent/子 Agent 之间仅传递路径。

建议目录结构（在项目内）：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”，并进行二次确认。

三条硬性规则

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

错误处理

• 对象不存在：使用 search_stripe_resources 或 fetch_stripe_resources 查找正确的 ID
• 参数错误：使用 search_stripe_documentation 查询正确的参数格式
• 权限不足：提示用户检查 API 密钥的权限范围
• 网络错误：建议重试或检查 MCP 连接状态