内容
# Stripe 本地服务器
用于 Stripe 支付操作的本地 [模型上下文协议](https://modelcontextprotocol.io/) 服务器。8 个领域中的 52 种工具，内置个人敏感信息删除和输入验证。
为 AI 辅助开发工作流而构建，Stripe API 访问默认情况下既全面又安全。
## 为什么存在
Stripe 官方远程 MCP 服务器（`mcp.stripe.com`）使用 OAuth 并包含文档搜索，但提供的工具集较小。此服务器在本地运行，涵盖了更多的 Stripe API 表面，并且在响应到达模型上下文之前进行净化，因此敏感数据永远不会泄漏到对话历史或日志中。
| | 本地服务器 | Stripe 官方 |
| ---------------- | ------------------------ | ---------------- |
| 传输方式 | stdio（本地） | HTTP（远程） |
| 认证方式 | `STRIPE_SECRET_KEY` 环境变量 | OAuth |
| 工具数量 | 52 | 较小的子集 |
| 个人敏感信息删除 | 内置 | Stripe 管理 |
| 文档搜索 | 否 | 是 |
| 幂等键 | 所有变更工具 | 取决于操作 |
| 输入验证 | 严格的模式（Zod） | 取决于操作 |
这两个服务器互相补充。如果您想要操作工具和文档搜索，可以同时运行它们。
## 工具（52）
### 客户（6）
`create_customer`、`retrieve_customer`、`update_customer`、`delete_customer`、`list_customers`、`search_customers`
### 支付（11）
`create_payment_intent`、`retrieve_payment_intent`、`confirm_payment_intent`、`capture_payment_intent`、`cancel_payment_intent`、`list_payment_intents`、`list_payment_methods`、`attach_payment_method`、`detach_payment_method`、`retrieve_charge`、`list_charges`
### 订阅（9）
`create_subscription`、`retrieve_subscription`、`update_subscription`、`cancel_subscription`、`list_subscriptions`、`create_product`、`list_products`、`create_price`、`list_prices`
### 发票（8）
`create_invoice`、`retrieve_invoice`、`finalize_invoice`、`pay_invoice`、`void_invoice`、`list_invoices`、`retrieve_upcoming_invoice`、`create_invoice_item`
### 结账（5）
`create_checkout_session`、`retrieve_checkout_session`、`list_checkout_sessions`、`create_coupon`、`list_coupons`
### 退款（3）
`create_refund`、`retrieve_refund`、`list_refunds`
### 余额（5）
`retrieve_balance`、`list_balance_transactions`、`list_payouts`、`list_disputes`、`retrieve_dispute`
### Webhooks（5）
`create_webhook_endpoint`、`delete_webhook_endpoint`、`list_webhook_endpoints`、`list_events`、`retrieve_event`
## 资源（4）
作为 MCP 资源公开（只读，已净化）：
- `stripe://account` - 当前账户详细信息
- `stripe://balance` - 按货币显示的余额
- `stripe://webhook-endpoints` - 已注册的 webhook 端点
- `stripe://products` - 具有默认价格的活动产品目录
## 提示（4）
用于常见集成任务的预建提示模板：
- `review_stripe_integration` - 安全、错误处理和最佳实践审计
- `setup_webhooks` - 每个框架的端到端 webhook 实现指南
- `design_pricing` - 使用 Stripe 产品和价格进行定价模型设计
- `troubleshoot_payment` - 诊断失败的支付、拒绝和纠纷
## 安全状况
每个 Stripe API 响应在到达 MCP 输出之前都会被净化：
- **隐藏机密**：webhook 签名机密、PaymentIntent `client_secret` 值，包括在扩展的嵌套对象中
- **屏蔽个人敏感信息**：电子邮件地址（显示前 2 个字符 + 域名）、电话号码（显示最后 4 位数字）、账单/发货地址完全净化
- **隐藏 URL**：托管的发票 URL 和发票 PDF 链接（带持有者样式的访问令牌）
- **净化元数据**：值被剥离，键被保留以提供操作员上下文
- **未知对象**：无法识别的 Stripe 对象类型被简化为最小的信封（`id`、`object`、`status`、`redacted: true`）而不是原始传递
- **输入验证**：Stripe ID、货币代码、webhook 事件名称、API 版本、结账支付方法类型和余额交易类型根据 Zod 模式验证。枚举验证器从安装的 Stripe SDK 的类型声明中导出启动时；如果这些文件在未来的 SDK 版本中更改形状，验证器会降级为允许所有，并带有 stderr 警告而不是崩溃
- **幂等性**：所有变更工具都接受可选的 `idempotency_key`（除了删除，Stripe 认为删除本质上是幂等的）
- **固定 API 版本**：`2026-05-27.dahlia`，在 `src/stripe-client.ts` 中设置
- **有界运行时**：网络重试次数上限为 0-5，超时上限为 1-120 秒
## 设置
### 先决条件
- 用于运行时的 Node.js 18+。用于运行测试的 Node ^20.19.0 或 >=22.12.0（Vite/Vitest 依赖项要求）
- 具有 API 密钥的 Stripe 账户（[dashboard.stripe.com/apikeys](https://dashboard.stripe.com/apikeys)）
### 安装和构建
```bash
git clone <repo-url>
cd stripe-mcp-server
npm install
npm run build
```
### 环境
```bash
cp .env.example .env
# 使用您的 Stripe 机密密钥编辑 .env
```
| 变量 | 必需 | 默认值 | 描述 |
| ---------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------ |
| `STRIPE_SECRET_KEY` | 是 | - | 机密密钥（`sk_test_…`、`sk_live_…`）或受限密钥（`rk_test_…`、`rk_live_…`） |
| `STRIPE_MAX_NETWORK_RETRIES` | 否 | `2` | 暂时性故障时的最大重试次数（0-5） |
| `STRIPE_TIMEOUT_MS` | 否 | `30000` | 请求超时（毫秒）（1000-120000） |
### 使用受限密钥
为了提高安全性，请使用 [受限密钥](https://docs.stripe.com/keys#limit-access)（`rk_*`）代替完整的机密密钥。每个工具组的最低权限：
| 工具组 | 所需权限 |
| ------------- | ---------------------------------------------------------------- |
| 客户 | 客户：读取/写入 |
| 支付 | PaymentIntents、PaymentMethods、Charges：读取/写入 |
| 订阅 | 订阅、产品、价格：读取/写入 |
| 发票 | 发票：读取/写入 |
| 结账 | 结账会话：读取/写入；优惠券：读取/写入 |
| 退款 | 退款：读取/写入（还需要 Charges 或 PaymentIntents：读取） |
| 余额 | 余额：读取；付款：读取；纠纷：读取 |
| Webhooks | Webhook 端点：读取/写入；事件：读取 |
仅授予您需要的组。只读工具（列表/检索）只需要其资源的读取权限。
### 连接到您的 MCP 客户端
#### Claude 代码（`.mcp.json`）
```json
{
"mcpServers": {
"stripe": {
"command": "node",
"args": ["/absolute/path/to/stripe-mcp-server/dist/index.js"],
"env": {
"STRIPE_SECRET_KEY": "sk_test_..."
}
}
}
}
```
#### VS Code（`.vscode/mcp.json`）
```json
{
"servers": {
"stripe": {
"command": "node",
"args": ["/absolute/path/to/stripe-mcp-server/dist/index.js"],
"env": {
"STRIPE_SECRET_KEY": "sk_test_..."
}
}
}
}
```
#### 其他 MCP 客户端
任何支持 stdio 传输的客户端都可以运行此服务器。将它指向 `dist/index.js`，并在环境中包含 `STRIPE_SECRET_KEY`。
## 验证
```bash
npm test # 42 个测试（净化、配置验证、模式检查）
npm run build # TypeScript 编译到 dist/
```
## 项目结构
```text
src/
index.ts # 服务器入口点，工具/资源/提示注册
stripe-client.ts # 具有固定版本和限定配置的 Stripe SDK 单例
tools/
balance.ts # 余额和付款工具
checkout.ts # 结账会话和优惠券工具
customers.ts # 客户 CRUD 和搜索
invoices.ts # 发票生命周期工具
payments.ts # PaymentIntent 和 PaymentMethod 工具
refunds.ts # 退款工具
subscriptions.ts # 订阅、产品和价格工具
webhooks.ts # Webhook 端点和事件工具
resources/index.ts # MCP 资源（账户、余额、webhooks、产品）
prompts/index.ts # MCP 提示模板
utils/stripe-toolkit.ts # 净化、验证模式、错误格式化
tests/
stripe-toolkit.test.ts # 净化和屏蔽测试
stripe-config-and-schemas.test.ts # 配置验证和模式测试
```
## 设计决策
**默认净化，而不是选择加入。** 每个 Stripe 对象类型都有明确的净化路径。未知对象类型被简化而不是直接传递。这意味着未来 API 版本中添加的新 Stripe 对象类型默认是安全的（它们显示 `id`、`status` 和 `redacted: true`，直到添加明确的处理程序）。
**从 Stripe 自己的类型定义中验证。** 结账付款方法类型、webhook 事件名称和 API 版本在启动时从安装的 Stripe SDK 的 TypeScript 声明文件中加载。当您升级 Stripe SDK 时，验证器会自动更新。如果 SDK 在未来的主要版本中重构其类型文件，验证器会降级为允许所有，并带有 stderr 警告而不是崩溃。无论验证器状态如何，通配符 `*` webhook 事件始终被拒绝。
**无存储状态。** 服务器在请求之间不持有任何数据，除了 Stripe SDK 客户端单例。所有状态都存在于 Stripe 的 API 中。
## 许可证
MIT
