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が公式ホストするBitrefill eCommerce MCP（https://api.bitrefill.com/mcp）に接続してください。Bitrefillがメンテナンスし、OAuthをサポートしており、実行、デプロイ、更新を自身で行うことなく同じツールを利用できます。

このリポジトリは、Bitrefill MCPの構築方法を学ぶ、フォークする、拡張する、またはBitrefill API v2上でカスタマイズ版をセルフホストする場合にご利用ください。

このサーバーはBitrefill API v2（https://api.bitrefill.com/v2）を**Authorization: Bearer ${BITREFILL_API_KEY}**を使用してラップします。リクエストパラメータのみが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アカウント → Developers。
環境変数（またはローカル実行用の.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}：ファミリーごとのカテゴリスラッグ

プロジェクトレイアウト

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クライアントインプロセス（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は単一のJSONブロブではなく、--tool-arg key=value（複数キーの場合は繰り返し）を使用します。ネストされたデータの場合は、値に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）を優先してください。

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