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 如何建構、複刻（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。

何時應改用此儲存庫

僅在您需要以下情況時，才執行此本地 MCP：

研究一個可運作的 Bitrefill MCP 伺服器參考實作。
複刻它以新增自訂工具、提示、驗證、日誌記錄或路由。
在私有網路或氣隙（air-gapped）環境中自行託管。
試驗更廣泛的 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 版的中斷性變更： 舊的 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