eSIMfly MCP

@esimfly/mcp — eSIMfly MCP サーバー

AI アシスタントから eSIMfly Business API を直接利用できます。この Model Context Protocol サーバーを使うと、Claude、Cursor、ChatGPT などの MCP クライアントで、卸売価格での eSIM プランの検索、残高と利用状況の確認、リアルタイムのネットワークデータに基づく 「データ通信なし」の問題の診断ができます。有効にした場合は、明示的な確認手順を経て注文やトップアップも行えます。

• デフォルトでは読み取り専用です。 オプトインしない限り、残高が消費されることはありません。
• 書き込みは2段階です。 すべての書き込みツールは、confirm: true を指定して呼び出すまで、プレビュー（内容、費用、残高）を返します。
• 公式の @esimfly/sdk を基盤としています — 署名、再試行、エラーコードを処理します。
• 2つのプロンプトを提供します。完全な統合ガイドと、eSIM の診断ワークフローです。

ドキュメント：https://docs.esimfly.net · 認証情報：Business Dashboard → Settings → API Keys。

ホステッドサーバー（インストール不要）

ローカルで何も実行したくない場合は、eSIMfly が同じサーバーを https://mcp.esimfly.net/mcp でホストしています。 Claude.ai、ChatGPT、Claude Code（claude mcp add --transport http esimfly https://mcp.esimfly.net/mcp）、 Cursor、または VS Code にリモート MCP サーバーとして追加し、eSIMfly のビジネスアカウントでサインインしてください。OAuth 2.1 を使用するため、キーを貼り付ける必要はありません。書き込み ツールは同意画面でオプトインします。詳細：https://docs.esimfly.net/docs/mcp-server

ローカルインストール

サーバーは stdio 経由でローカルに実行され、API キーがマシンの外に出ることはありません。

Claude Desktop

claude_desktop_config.json → mcpServers：

{
  "mcpServers": {
    "esimfly": {
      "command": "npx",
      "args": ["-y", "@esimfly/mcp"],
      "env": {
        "ESIMFLY_ACCESS_CODE": "esf_...",
        "ESIMFLY_SECRET_KEY": "sk_..."
      }
    }
  }
}

Claude Code

claude mcp add esimfly -e ESIMFLY_ACCESS_CODE=esf_... -e ESIMFLY_SECRET_KEY=sk_... -- npx -y @esimfly/mcp

Cursor / Windsurf / その他の MCP クライアント

.cursor/mcp.json（またはクライアントに相当する設定ファイル）：

{
  "mcpServers": {
    "esimfly": {
      "command": "npx",
      "args": ["-y", "@esimfly/mcp"],
      "env": { "ESIMFLY_ACCESS_CODE": "esf_...", "ESIMFLY_SECRET_KEY": "sk_..." }
    }
  }
}

Docker

docker build -t esimfly-mcp .
docker run -i --rm -e ESIMFLY_ACCESS_CODE=esf_... -e ESIMFLY_SECRET_KEY=sk_... esimfly-mcp

書き込みツールを有効にする

env に "ESIMFLY_MCP_ALLOW_WRITES": "true" を追加します。設定しない場合、注文、トップアップ、キャンセル、 一時停止、SMS、Webhook のツールは登録すらされません。

試してみる

• 「トルコで最も安い 5 GB のプランを探して、€9.99 での利益率を教えてください。」
• 「私の eSIM のうち、アクティブで残り 200 MB 未満のものはどれですか？」
• 「ICCID 8948010010036785060 でデータ通信ができません。診断してください。」（diagnose_esim プロンプトを使用）
• 「https://my.app/hooks で、インストール済み／ステータス／データ残量低下のイベント用に Webhook を設定してください。」（書き込みツール。最初にプレビューを表示）
• 「Node.js の統合を作ってください。」（esimfly_integration_guide プロンプトを使用）

ツール

ツール	機能	モード
search_packages	仕入れ価格で渡航先／種類別にカタログを検索します	読み取り
get_balance	アカウント（または法人アカウント）の残高を取得します	読み取り
list_esims	ステータス、残りデータ量、有効期間を含むお使いの eSIM を一覧表示します	読み取り
get_esim_usage	1 枚の eSIM の保存済み使用量を取得します（低コスト）	読み取り
get_esim_live_status	ネットワークからリアルタイムのステータスを取得します：インストール状態、直近のネットワーク、デバイス、使用量	読み取り（高コスト）
get_network_events	過去 7 日間の接続／データセッションイベントと誤ったネットワークのフラグを取得します	読み取り
get_usage_report	国と通信事業者別の日次使用量を取得します（最大 90 日間）	読み取り
list_orders / get_order	注文履歴、および eSIM を含む 1 件の注文を取得します	読み取り
get_topup_packages	1 枚の eSIM で利用できるデータ追加オプションを取得します	読み取り
get_webhook_settings	Webhook URL、イベント、最近の配信を取得します	読み取り
create_order	eSIM を購入します — プレビュー後、confirm: true と冪等性キーを指定します	書き込み
topup_esim	eSIM にデータを追加します — プレビューにパッケージと料金が表示されます	書き込み
cancel_esim	未使用の eSIM をキャンセルし、残高に返金します	書き込み（破壊的）
suspend_esim / activate_esim	ネットワークアクセスをブロック／復元します	書き込み
send_sms	eSIM を利用しているデバイスにテキストメッセージを送信します	書き込み
set_webhook	Webhook URL とイベントを設定します	書き込み

プロンプト：esimfly_integration_guide（stack は任意）、diagnose_esim（iccid）。

安全性モデル

• ESIMFLY_MCP_ALLOW_WRITES=true が設定されていない限り、読み取り専用です。
• 書き込みツールは 2 段階方式です。confirm を指定せずに呼び出すとプレビューを返し、変更を伴う API 呼び出しは行いません。 create_order ではさらに、独自のプレビューから取得した idempotency_key が必要となるため、エージェントが同じ注文を 2 回行うことはありません。
• ツールのアノテーションでは、読み取りに readOnlyHint、キャンセル／停止に destructiveHint が設定されているため、リスクの高いツールでユーザー承認を求めるホストでは、そのように動作します。
• サーバーは認証情報を記録せず、MCP プロトコル以外の内容を標準出力に書き込みません。
• エージェントには、許容できる範囲で最小のレート制限を設定した専用 API キーを付与してください。不安がある場合は、ダッシュボードからキーをローテーションしてください。

設定

変数	必須	説明
ESIMFLY_ACCESS_CODE	はい	API アクセスコード（esf_…）
ESIMFLY_SECRET_KEY	はい	API シークレットキー（sk_…）
ESIMFLY_MCP_ALLOW_WRITES	いいえ	書き込みツールを登録するには true を指定します
ESIMFLY_BASE_URL	いいえ	API ベース URL を上書きします

埋め込み

import { createEsimflyMcpServer } from '@esimfly/mcp';
const server = createEsimflyMcpServer({ config: { accessCode, secretKey }, allowWrites: false });
// connect it to any MCP transport

リリース（メンテナー向け）

package.json と server.json の version、および src/server.ts の MCP_VERSION を更新し、CHANGELOG エントリを追加してプッシュします。その後、vX.Y.Z タグを付けた GitHub Release を公開します。ワークフローによって Trusted Publishing（OIDC）で npm に公開され、その後 MCP Registry のエントリも自動的に再公開されます（GitHub OIDC を使用し、トークンは不要です）。

サポート

[email protected] · https://docs.esimfly.net