用途
mcp-stripe 是一个通过 Stripe MCP 服务器（https://mcp.stripe.com）执行 Stripe 交易操作的技能，用于在对话或工作流中完成客户、产品、价格、发票、支付链接、优惠券、退款、争议和订阅等账单相关操作。
主要能力
该技能提供的工具按类别划分：
- 账户：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（创建可分享的支付链接）
- 支付意图：list_payment_intents（仅查询）
- 退款：create_refund（危险操作，需确认）
- 争议：list_disputes、update_dispute（update 需确认）
- 订阅：list_subscriptions、update_subscription、cancel_subscription（update/cancel 需确认）
- 优惠券：create_coupon、list_coupons（创建/列出优惠券）
- 搜索：search_stripe_resources、fetch_stripe_resources、search_stripe_documentation（搜索对象/文档）
无法完成的操作（不在工具列表中）：
- 无法直接创建 PaymentIntent / 扣款
- 无法创建订阅（create_subscription）
- 无法创建促销代码（Promotion Code，仅支持优惠券）
- 无法删除对象
使用方式
连接配置
MCP 服务器：https://mcp.stripe.com
Claude Code 连接命令：
claude mcp add --transport http stripe https://mcp.stripe.com/
claude /mcp # authenticate
认证方式：优先使用 OAuth；如需 API key，使用受限密钥作为 Bearer token。
模式：默认测试模式。切换到实时模式需要用户明确说出“live”并二次确认。
三条硬性规则
- 写前先读：在创建客户/产品/价格之前，先用 list_* 或 search_stripe_resources 检查是否已存在，避免重复对象。
- 资金与合同需确认：create_refund、cancel_subscription、update_subscription、update_dispute 必须先展示内容并获得用户明确确认后才能执行。
- 不确定时先搜索：如果不确定对象 ID、字段或方法，先调用 search_stripe_documentation 或 search_stripe_resources，不要猜测参数。
危险操作处理流程
在执行 create_refund、cancel_subscription、update_subscription、update_dispute 之前：
- 先展示：列出要操作的对象 ID 和关键字段
- 说明影响：退款金额/取消时间/变更内容
- 请求确认：等待用户明确回复“confirm”/“yes”/“proceed”
- 执行并回执：返回操作结果 + 对象 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 + 关键字段 + 下一步
基于文件的流水线（仅传递路径）
将账单操作集成到多步骤工作流时，将所有上下文和产物持久化到磁盘，仅在代理/子代理之间传递路径。
推荐目录结构（项目内）：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（每次工具调用的摘要；不要逐字记录敏感信息）
常见工作流
创建客户
- 用 search_stripe_resources 或 list_customers 检查是否已存在
- 如不存在，create_customer(name, email, metadata)
- 返回 cus_xxx + 关键信息
创建产品与价格
- list_products 检查产品是否已存在
- create_product(name, description)
- create_price(product=prod_xxx, unit_amount=最小单位金额, currency="gbp", 如需则 recurring)
- 返回 prod_xxx + price_xxx
创建并发送发票
- 确认客户 ID（未知则用 list_customers 查询）
- create_invoice(customer=cus_xxx, collection_method, days_until_due)
- create_invoice_item(invoice=inv_xxx, price=price_xxx, quantity)
- finalize_invoice(invoice=inv_xxx)
- 返回 inv_xxx + hosted_invoice_url
创建支付链接
- 确认价格 ID（未知则用 list_prices 查询）
- create_payment_link(line_items=[{price, quantity}], 如需 after_completion)
- 返回支付链接 URL
退款（危险）
- list_payment_intents 找到目标支付
- 展示 pi_xxx + 金额 + 客户信息
- 请求用户确认
- 确认后 create_refund(payment_intent=pi_xxx, 部分退款时填 amount, reason)
- 返回 re_xxx + 状态
取消订阅（危险）
- list_subscriptions(customer=cus_xxx) 找到目标
- 展示 sub_xxx + 当前状态 + 下次账单日期
- 询问：立即取消还是周期结束时取消（cancel_at_period_end）
- 确认后 cancel_subscription(subscription=sub_xxx)
- 返回取消结果
适用场景
适用于需要在对话或自动化工作流中执行 Stripe 账单操作的场景，例如创建客户、配置产品与价格、生成并发送发票、创建支付链接、发放优惠券、处理退款、管理争议和订阅等。也适合将账单操作嵌入多步骤代理工作流，通过基于文件的流水线传递上下文。
限制
- 无法直接创建 PaymentIntent / 扣款
- 无法创建订阅（create_subscription）
- 无法创建促销代码（仅支持优惠券）
- 无法删除对象
- 默认测试模式，实时模式需明确说明并二次确认
- 涉及资金与合同的操作必须获得用户明确确认
错误处理
- 对象不存在：使用 search_stripe_resources 或 fetch_stripe_resources 查找正确 ID
- 参数错误：使用 search_stripe_documentation 查询正确参数格式
- 权限不足：提示用户检查 API key 权限范围
- 网络错误：建议重试或检查 MCP 连接状态
工具参数详情参见 tools.md。