Bitrefill MCP Server

Bitrefill MCP 服务（示例实现）

这是一个示例／参考实现。 用于生产环境时，请改用 Bitrefill 官方托管的电商 MCP：https://api.bitrefill.com/mcp。该服务由 Bitrefill 维护，支持 OAuth，并提供相同的工具，无需自行运行、部署或更新。

如果你想了解如何构建 Bitrefill MCP、创建分支、扩展功能，或基于 Bitrefill API v2 自托管定制版本，请使用此代码仓库。

此服务通过 Authorization: Bearer ${BITREFILL_API_KEY} 封装 Bitrefill API v2（https://api.bitrefill.com/v2）。只有请求参数会通过 Zod 验证；API 响应会以未经修改的 JSON 文本形式返回。

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

Bitrefill 电商 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。

何时改用此代码仓库

只有在需要以下功能时，才运行此本地 MCP：

• 学习 Bitrefill MCP 服务的可运行参考实现。
• 创建分支，添加自定义工具、提示词、验证、日志记录或路由。
• 在私有网络或隔离网络环境中自托管。
• 尝试更多 v2 端点（此示例提供 18 个工具，而官方远程 MCP 刻意仅提供精选的 7 个工具；请参阅 电商 MCP）。

对于日常的“让我的 AI 助手购买礼品卡／eSIM”使用场景，建议使用上面的托管服务。

配置

1. 创建 API 密钥：Bitrefill 账户 → 开发者。
2. 在环境变量中设置（本地运行时也可写入 .env）：

BITREFILL_API_KEY=your_api_key_here

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

工具（v1.0.0）

工具	API
search-products	GET /products/search（带 q）或 GET /products（浏览）
product-details	GET /products/{id}
buy-products	POST /invoices
get-invoice-by-id	GET /invoices/{id}
get-order-by-id	GET /orders/{id}
list-invoices	GET /invoices
list-orders	GET /orders
pay-invoice	POST /invoices/{id}/pay
get-account-balance	GET /accounts/balance
check-phone-number	GET /check_phone_number
ping	GET /ping
list-esim-products	GET /products/esims
get-esim-product	GET /products/esims/{id}
create-esim-invoice	POST /esims
get-esim-invoice	GET /esims/invoice/{id}
pay-esim-invoice	POST /esims/invoice/{id}/pay
list-esims	GET /esims
get-esim	GET /esims/{id}

**相较于 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 块。对于嵌套数据，请在值中使用 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 电商 MCP（托管）：官方远程服务，推荐用于生产环境
• 设置指南：ChatGPT、Claude、Cursor

许可证

MIT