mcp-stripe

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Stripe MCP Transaction Skill

Stripe MCP 交易操作Skill

Execute transaction operations via Stripe MCP server.

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

File-based Pipeline (Pass Paths Only)

基于文件的流水线（仅传递路径）

When integrating billing operations into multi-step workflows, persist all context and artifacts to disk, passing only paths between agents/sub-agents.

Recommended directory structure (within project):

runs/<workflow>/active/<run_id>/

Input:
```
01-input/goal.md
```
(requirements),
```
01-input/context.json
```
(known customer/invoice/subscription/payment_intent IDs, etc.)
Plan:
```
03-plans/stripe-actions.md
```
(list of operations to execute; money/contracts must be written here and await confirmation first)
Output:
```
05-final/receipt.md
```
+
```
05-final/receipt.json
```
(object type + ID + key fields + next steps)
Logs:
```
logs/events.jsonl
```
(summary of each tool call; do not log sensitive information verbatim)

在将计费操作集成到多步骤工作流时，将所有上下文和工件持久化到磁盘，仅在代理/子代理之间传递路径。

推荐的目录结构（项目内）：

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
```
（每个工具调用的摘要；不要逐字记录敏感信息）

Connection Configuration

连接配置

MCP Server:

https://mcp.stripe.com

Claude Code Connection:

bash

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

Authentication: OAuth preferred; if API key needed, use restricted key as Bearer token.

Mode: Test mode by default. Switching to live requires user to explicitly say "live" and double confirmation.

MCP服务器：

https://mcp.stripe.com

Claude Code 连接:

bash

claude mcp add --transport http stripe https://mcp.stripe.com/
claude /mcp  # 进行身份验证

身份验证：首选OAuth；如果需要API密钥，请使用受限密钥作为Bearer令牌。

模式：默认测试模式。切换到生产模式需要用户明确说出“live”并进行双重确认。

Three Hard Rules

三条硬性规则

Read before write - Before creating customer/product/price, first use
```
list_*
```
or
```
search_stripe_resources
```
to check if it already exists, avoid duplicate objects
Money and contracts require confirmation -
```
create_refund
```
,
```
cancel_subscription
```
,
```
update_subscription
```
,
```
update_dispute
```
must display content and get explicit user confirmation before execution
When in doubt, search - If unsure about object ID, fields, or approach, first call
```
search_stripe_documentation
```
or
```
search_stripe_resources
```
, don't guess parameters

先读后写 - 在创建客户/产品/价格之前，先使用
```
list_*
```
或
```
search_stripe_resources
```
检查是否已存在，避免重复对象
资金和合同需要确认 -
```
create_refund
```
、
```
cancel_subscription
```
、
```
update_subscription
```
、
```
update_dispute
```
必须显示内容并获得用户明确确认后才能执行
存疑即搜索 - 如果不确定对象ID、字段或方法，请先调用
```
search_stripe_documentation
```
或
```
search_stripe_resources
```
，不要猜测参数

Available Tools

可用工具

Category	Tool	Description
Account	`get_stripe_account_info`	Get account info
Balance	`retrieve_balance`	Query available/pending balance
Customer	`create_customer` , `list_customers`	Create/list customers
Product	`create_product` , `list_products`	Create/list products
Price	`create_price` , `list_prices`	Create/list prices
Invoice	`create_invoice` , `create_invoice_item` , `finalize_invoice` , `list_invoices`	Full invoice workflow
Payment Link	`create_payment_link`	Create shareable payment link
Payment Intent	`list_payment_intents`	List payment intents (query only)
Refund	`create_refund`	⚠️ Dangerous - requires confirmation
Dispute	`list_disputes` , `update_dispute`	⚠️ update requires confirmation
Subscription	`list_subscriptions` , `update_subscription` , `cancel_subscription`	⚠️ update/cancel require confirmation
Coupon	`create_coupon` , `list_coupons`	Create/list coupons
Search	`search_stripe_resources` , `fetch_stripe_resources` , `search_stripe_documentation`	Search objects/documentation

Cannot do (not in tool list):

❌ Create PaymentIntent / charge directly
❌ Create subscription (create_subscription)
❌ Create Promotion Code (only coupon)
❌ Delete objects

分类	工具	描述
账户	`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`	搜索对象/文档

无法执行的操作（不在工具列表中）：

❌ 直接创建Payment Intent / 扣款
❌ 创建订阅（create_subscription）
❌ 创建促销代码（仅支持优惠券）
❌ 删除对象

Dangerous Action Handling Flow

危险操作处理流程

Before executing

create_refund

cancel_subscription

update_subscription

update_dispute

Display first - List the object ID and key fields to be operated on
Explain impact - Refund amount/cancellation time/change content
Request confirmation - Wait for user to explicitly reply "confirm"/"yes"/"proceed"
Execute and receipt - Return operation result + object ID + status

Example confirmation prompt:

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

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

在执行

create_refund

、

cancel_subscription

、

update_subscription

、

update_dispute

之前：

先显示信息 - 列出要操作的对象ID和关键字段
说明影响 - 退款金额/取消时间/变更内容
请求确认 - 等待用户明确回复“confirm”/“yes”/“proceed”
执行并返回回执 - 返回操作结果 + 对象ID + 状态

确认提示示例：

即将执行退款：
- PaymentIntent: pi_xxx
- 金额：£50.00（全额）
- 原因：requested_by_customer

回复“confirm”继续，或“cancel”中止。

Default Configuration

默认配置

Currency: Prioritize user-specified currency; if not specified, use existing object currency (Price/Invoice/PaymentIntent); if still unclear, ask
Amount: Accept decimal input, auto-convert to smallest unit integer (e.g., £19.99 → 1999)
Output receipt: Object type + ID + key fields + next steps

货币：优先使用用户指定的货币；如果未指定，使用现有对象的货币（Price/Invoice/PaymentIntent）；如果仍不明确，则询问用户
金额：接受小数输入，自动转换为最小单位整数（例如：£19.99 → 1999）
输出回执：对象类型 + ID + 关键字段 + 后续步骤

Common Workflows

常见工作流

Create Customer

创建客户

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. 使用search_stripe_resources或list_customers检查是否已存在
2. 如果不存在，调用create_customer(name, email, metadata)
3. 返回cus_xxx + 关键信息

Create Product and Price

创建产品和价格

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. 使用list_products检查产品是否已存在
2. 调用create_product(name, description)
3. 调用create_price(product=prod_xxx, unit_amount=最小单位金额, currency="gbp", 如需 recurring 参数则添加)
4. 返回prod_xxx + price_xxx

Create and Send Invoice

创建并发送发票

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. 确认客户ID（如果未知，使用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. 返回inv_xxx + hosted_invoice_url

Create Payment Link

创建支付链接

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. 确认价格ID（如果未知，使用list_prices查询）
2. 调用create_payment_link(line_items=[{price, quantity}], 如需 after_completion 参数则添加)
3. 返回支付链接URL

Refund (Dangerous)

退款（危险操作）

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_payment_intents找到目标支付记录
2. 显示pi_xxx + 金额 + 客户信息
3. 请求用户确认
4. 确认后，调用create_refund(payment_intent=pi_xxx, 部分退款金额, reason)
5. 返回re_xxx + 状态

Cancel Subscription (Dangerous)

取消订阅（危险操作）

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

1. 使用list_subscriptions(customer=cus_xxx)找到目标订阅
2. 显示sub_xxx + 当前状态 + 下一个计费日期
3. 询问：立即取消还是在计费周期结束时取消（cancel_at_period_end）
4. 确认后，调用cancel_subscription(subscription=sub_xxx)
5. 返回取消结果

Tool Parameter Details

工具参数详情

See tools.md

查看 tools.md

Error Handling

错误处理

Object doesn't exist: Use search_stripe_resources or fetch_stripe_resources to find correct ID
Parameter error: Use search_stripe_documentation to query correct parameter format
Insufficient permissions: Prompt user to check API key permission scope
Network error: Suggest retry or check MCP connection status

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