Stripe MCP Server

MCP（模型上下文协议）服务器，将 Stripe API 暴露给 Claude。 设计用于在 Railway 上以只读模式部署。

👉 部署步骤见 DEPLOY-RAILWAY.md。

功能

为 Claude 提供 17 个工具来查询 Stripe：客户、收款、支付、订阅、发票、目录、余额、交易、payouts、事件和争议——外加一个可访问任意端点的通用工具、一个可按 id 解析任意对象的工具，以及一个收入汇总报告。

Related MCP server: Stripe MCP Server

环境变量

三道写入闸门

Stripe 涉及真实资金：一个错误的 POST 可能会退款给客户、取消订阅或永久删除记录。因此有三道独立的锁，任何写入都必须通过全部三道。

1. STRIPE_READ_ONLY — 默认值取决于传输方式

• stdio（本地）： 默认允许写入。只有可信用户在自有机器上使用。

• http（远程）： 默认阻止写入。必须特意设置 STRIPE_READ_ONLY=0 才能启用。

在公开部署中忘记设置该变量会使其保持只读，而不是开放。

2. STRIPE_ALLOW_LIVE_WRITES — live 模式闸门

即使关闭了只读，live key 仍会拒绝写入，直到设置 STRIPE_ALLOW_LIVE_WRITES=1。测试 key（sk_test_、rk_test_）不经过此闸门：针对测试数据进行实验不应需要额外仪式。

3. confirm=true — 端点级闸门

破坏性端点（/v1/refunds、/v1/payouts、/v1/transfers、取消订阅、删除客户、关闭争议）除了上述要求外，还必须在调用中携带 confirm=true。误触发的工具无法自行到达那里。

每次拒绝都会说明是哪一道闸门阻止了它。

端点认证

MCP 协议本身不提供认证。在 http 模式下，此服务器要求每个请求都带有 Authorization: Bearer <MCP_AUTH_TOKEN>，或者将密钥嵌入路径（/s/<secreto>/mcp）供 Claude 连接器使用。/healthz 是唯一公开路由。

如果 MCP_AUTH_TOKEN 缺失或少于 32 个字符，服务器拒绝启动。这是有意为之：避免因疏忽而将通往 Stripe 账户的开放网关公之于众。

本地运行

pip install -r requirements.txt

# stdio (para Claude Desktop)
STRIPE_API_KEY=rk_test_xxx python stripe_mcp.py

# http (como en Railway)
STRIPE_MCP_TRANSPORT=http \
STRIPE_API_KEY=rk_test_xxx \
MCP_AUTH_TOKEN=$(python3 -c "import secrets;print(secrets.token_urlsafe(48))") \
PORT=8000 python stripe_mcp.py

启动时会打印最终所处的模式：

[stripe-mcp] streamable-http on 0.0.0.0:8000  mode=test  read_only=True  allow_live_writes=False  writes_enabled=False

关于 Stripe API 的说明

服务器已为你处理的一些事项，以及阅读响应时值得了解的内容：

• Stripe 不接受 JSON 作为请求体。 所有内容都使用 application/x-www-form-urlencoded 格式，并采用方括号表示法：metadata[order]=6735、expand[]=customer、items[0][price]=price_1。服务器仅转换嵌套的字典和列表。

• 金额是最小单位的整数。 2500 配合 usd 表示 $25.00。有些货币没有小数位（JPY、KRW、CLP...），此时整数就是金额——除以 100 会出错。格式化输出会尊重这一点。

• 测试环境和 live 环境是独立的宇宙。 在测试环境创建的 id 使用 live key 会返回 404，反之亦然。这是 id 正确却出现 404 的最常见原因。

• 分页基于游标而非页码。 取最后一个 id 作为 starting_after 传入。当还有更多数据时，响应会包含 next_page_hint，其中带有确切的值。

• 没有 PATCH 或 PUT。 Stripe 使用 POST 来创建和更新。只有 GET、POST 和 DELETE。

• 列表不会按 status 过滤 charges 或 payment_intents。需要对返回的记录进行过滤，或使用 stripe_search。

• stripe_list_subscriptions 默认省略已取消的订阅。 对于流失相关的问题，必须传递 status='all'，否则响应会静默出错。

• 搜索索引最多需要一分钟才能看到新创建的对象。对于新对象，请按 id 查找。

• 事件仅保留 30 天。 更早的数据需要查看对象本身。

• 没有聚合端点。 因此 stripe_revenue_summary 在 MCP 服务器端分页并求和，当页数上限截断计数时会以 complete=false 提示——这些总计是部分结果，不应作为最终数据报告。

• 每个 POST 都会携带 Idempotency-Key，因此重试不会重复扣费。Stripe 会记住它们 24 小时。

安全

• 密钥放在环境变量中，绝不写入代码。.gitignore 会阻止 .env 文件。

• 使用 restricted key（rk_...），而不是 secret key。 可以在仪表盘中随意创建，并按资源授予权限。对于此部署：所有资源设为 Read，Write 全部关闭。sk_live_ 会提供账户的完全访问权限，包括移动资金。

• 共享单一 token 意味着无法按人追踪。任何人的操作都会记录为同一个 key。

• 没有内置速率限制。拥有 MCP_AUTH_TOKEN 的人可以持续请求 Stripe，直到触及 Stripe 的限制（live 环境约 100 次读取/秒）。

• 要立即切断访问：在 https://dashboard.stripe.com/apikeys 删除 restricted key——服务器会立刻失效。