Bitrefill

官方

购买礼品卡、eSIM、手机充值。支持银行卡和加密货币支付。

GitHub

你可以用 Bitrefill MCP 做什么？

搜索礼品卡和eSIM — 通过关键词查找可用产品，或使用 search-products 浏览完整目录。
查看产品详情 — 使用 product-details 获取特定产品的定价、面额和地区信息。
购买礼品卡或eSIM — 通过 buy-products 或 create-esim-invoice 创建购买发票。
支付发票 — 使用 pay-invoice 或 pay-esim-invoice 完成待处理的购买支付。
查询订单或发票 — 使用 get-order-by-id 或 get-invoice-by-id 获取状态和兑换信息。
检查账户余额 — 使用 get-account-balance 查看当前 Bitrefill 余额。

文档

Bitrefill MCP 服务器（示例实现）

这是一个示例/参考实现。 对于生产环境，请改为连接到 官方托管的 Bitrefill eCommerce 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 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。

何时改用此仓库

仅在需要时运行此本地 MCP：

研究 Bitrefill MCP 服务器的可用参考实现。
复刻它以添加自定义工具、提示、验证、日志记录或路由。
在私有网络或气隙环境中自托管。
试验更广泛的 v2 端点集（此示例公开了 18 个工具，而官方远程 MCP 有意公开了精选的 7 个；请参阅 eCommerce MCP）。

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

配置

创建一个 API 密钥：Bitrefill 账户 → 开发者。
在环境中设置（或用于本地运行的 .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 版本相比的重大变更： 旧的蛇形命名工具名称（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}：每个系列的类别标识

项目布局

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 eCommerce MCP（托管）：官方远程服务器，推荐用于生产环境
设置指南：ChatGPT、Claude、Cursor

许可证

MIT