Bitrefill MCP Server

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（推奨）。クライアントに次の URL を指定します。

  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 を購入する」といった日常的な用途には、上記のホスト型サーバーをおすすめします。

設定

1. API キーを作成します：Bitrefill アカウント → Developers。
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}：各ファミリーのカテゴリーのスラッグ

プロジェクト構成

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 への stdio 接続）。

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

クライアントの例（セルフホスト用サンプル）

注意：本番環境では、以下の stdio 設定ではなく、ホスト型の 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