Bitrefill MCP 服务器（示例实现）

这是一个示例/参考实现。 如需生产使用，请连接至 Bitrefill 官方托管的 eCommerce MCP，地址为 https://api.bitrefill.com/mcp。该服务由 Bitrefill 维护，支持 OAuth，并公开了相同的工具，无需您自行运行、部署或更新任何内容。

如果您想 了解如何构建 Bitrefill MCP、派生（fork）它、扩展它，或者在 Bitrefill API v2 之上 自托管自定义变体，请使用此仓库。

此服务器使用 Authorization: Bearer ${BITREFILL_API_KEY} 封装了 Bitrefill API v2 (https://api.bitrefill.com/v2)。仅 请求 参数通过 Zod 进行验证；API 响应将作为 JSON 文本原样返回。

使用官方远程 MCP（生产环境推荐）

Bitrefill eCommerce MCP 由 Bitrefill 托管，是与 ChatGPT、Claude Desktop / Code、Cursor 以及任何其他兼容 MCP 的客户端集成的推荐方式。

• OAuth（推荐）。将您的客户端指向：

  https://api.bitrefill.com/mcp

  您将被重定向到 Bitrefill 进行登录并授权访问。无需处理 API 密钥。

• API 密钥。附加您从 bitrefill.com/account/developers 获取的密钥：

  https://api.bitrefill.com/mcp/YOUR_API_KEY

各客户端设置指南：ChatGPT, Claude Desktop, Claude Code, Cursor。

Related MCP server: Armor Crypto MCP

何时使用此仓库

仅在以下情况运行此本地 MCP：

• 研究 Bitrefill MCP 服务器的工作参考实现。

• 派生它以添加自定义工具、提示词、验证、日志记录或路由。

• 在私有网络或物理隔离环境中自托管。

• 尝试更广泛的 v2 端点（此示例公开了 18 个工具，而官方远程 MCP 有意仅公开了精选的 7 个；请参阅 eCommerce MCP）。

对于日常“让 AI 助手购买礼品卡/eSIM”的使用场景，请优先使用上述托管服务器。

配置

1. 创建 API 密钥：Bitrefill 账户 → 开发者。

2. 在环境变量中设置（或在本地运行时使用 .env 文件）：

BITREFILL_API_KEY=your_api_key_here

如果缺少 BITREFILL_API_KEY，则 不会注册任何工具（v2 即使对于 ping 也需要身份验证）。

工具 (v1.0.0)

相对于 0.x 的重大变更： 旧的 snake_case 工具名称（search, create_invoice, unseal_order 等）已被移除。请使用上述名称。v2 中没有 unseal_order；GET /orders/{id} 在交付时会返回 redemption_info。

资源

• bitrefill://payment-methods: 用于 buy-products / create-esim-invoice 的允许的 payment_method 字符串

• bitrefill://category-slugs: 用于产品列表/搜索的 B2B category 查询值

• bitrefill://product-types: 产品系列键

• bitrefill://product-types/{productType}: 每个系列的类别 slug

项目布局

src/
  index.ts
  types/api.ts          # Optional TS shapes for API JSON (not validated at runtime)
  constants/            # payment_method list, category slugs
  handlers/             # resources.ts, tools.ts
  schemas/              # Zod: inputs only
  services/             # API calls (search, products, invoices, orders, esims, misc)
  utils/api/            # base (BitrefillApiError), authenticated (Bearer v2)

开发

pnpm install
pnpm run build
pnpm run typecheck
pnpm run lint

冒烟测试（仅限此仓库的 MCP）

冒烟测试始终启动 此包的 服务器（在 pnpm run build 之后运行 node build/index.js）。它们 不会 打开 https://api.bitrefill.com/mcp 或任何其他远程 MCP URL。

推荐：MCP 客户端进程内（stdio 到 build/index.js）：

pnpm run build
pnpm run smoke

与 pnpm run test-services（别名）相同。

可选：MCP Inspector CLI，仍然仅针对 此 服务器：

pnpm run build
pnpm run smoke:inspector

全部 18 个工具（Inspector CLI，摘要行，特意使用虚拟 ID）：

pnpm run test:inspector:all-tools

Inspector 使用 --tool-arg key=value（多个键重复此操作），而不是单个 JSON blob。对于嵌套数据，请在值中使用 JSON，例如 --tool-arg 'products=[{"product_id":"x","value":10}]'。

交互式 UI（仅限本地服务器）：

pnpm run build
pnpm run inspector

示例：

pnpm dlx @modelcontextprotocol/inspector node build/index.js --cli --method tools/call --tool-name ping
pnpm dlx @modelcontextprotocol/inspector node build/index.js --cli --method tools/call --tool-name product-details --tool-arg id=test-gift-card-code

客户端示例（自托管示例）

提醒：对于生产环境，请优先使用托管的 https://api.bitrefill.com/mcp (OAuth)，而不是下方的 stdio 配置。

Cursor / Claude 风格的 MCP 配置，在 env 中传递密钥：

{
  "mcpServers": {
    "bitrefill": {
      "command": "npx",
      "args": ["-y", "bitrefill-mcp-server"],
      "env": {
        "BITREFILL_API_KEY": "your_api_key_here"
      }
    }
  }
}

Docker，例如 -e BITREFILL_API_KEY=... 或 --env-file .env。

托管的远程 MCP（无需安装，推荐）：

{
  "mcpServers": {
    "bitrefill": {
      "url": "https://api.bitrefill.com/mcp"
    }
  }
}

文档

• Bitrefill 文档 (llms 索引)

• Bitrefill eCommerce MCP (托管)：官方远程服务器，生产环境推荐

• 设置指南：ChatGPT, Claude, Cursor

许可证

MIT