eSIMfly MCP

@esimfly/mcp — eSIMfly MCP 服务

让你的 AI 助手能够使用 eSIMfly Business API。通过这个 Model Context Protocol 服务，Claude、Cursor、ChatGPT 和其他 MCP 客户端可以按你的批发价格搜索 eSIM 套餐、查看余额和用量、根据实时网络数据诊断 “无数据”问题；如果你启用相关功能，还可以下单和充值，但需要经过明确的确认步骤。

• 默认只读。 除非你主动启用，否则不会消耗余额。
• 两步写入。 每个写入工具都会返回预览（操作内容、费用、余额），直到调用时传入 confirm: true。
• 基于官方 @esimfly/sdk 构建 — SDK 负责签名、重试和错误代码。
• 提供两个提示词：完整集成指南和 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

启用写入工具

将 "ESIMFLY_MCP_ALLOW_WRITES": "true" 添加到 env。否则，下单、充值、取消、 暂停、SMS 和 webhook 工具都不会注册。

试用

• “查找土耳其最便宜的 5 GB 套餐，并告诉我按 €9.99 定价时的利润。”
• “我的哪些 eSIM 正在使用中，且剩余流量低于 200 MB？”
• “ICCID 8948010010036785060 显示无数据 — 帮我诊断。” （使用 diagnose_esim 提示词）
• “为已安装 / 状态 / 低流量事件设置 webhook，地址为 https://my.app/hooks。” （写入工具，会先显示预览）
• “帮我构建一个 Node.js 集成。” （使用 esimfly_integration_guide 提示词）

工具

工具	功能	模式
search_packages	按目的地 / 类型搜索套餐目录，并显示您的成本价	读取
get_balance	账户（或企业）余额	读取
list_esims	您的 eSIM，包含状态、剩余流量和有效期	读取
get_esim_usage	单张 eSIM 的已存储用量（成本低）	读取
get_esim_live_status	从网络获取实时状态：安装状态、上次连接的网络、设备、用量	读取（成本高）
get_network_events	最近 7 天的连接 / 数据会话事件，以及网络错误标记	读取
get_usage_report	按国家和运营商统计的每日用量（最多 90 天）	读取
list_orders / get_order	订单历史记录，以及包含其 eSIM 的单笔订单	读取
get_topup_packages	单张 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。
• 写入工具分为两步：不传入 confirm 的调用会返回预览，不会调用任何可变更数据的 API； create_order 还需要传入其预览中返回的 idempotency_key，因此 Agent 无法重复下单。
• 工具注释将读取操作标记为 readOnlyHint，将取消 / 暂停操作标记为 destructiveHint，因此会在危险工具上征求用户批准的宿主会照此执行。
• 服务绝不会记录凭据，也绝不会将 MCP 协议以外的内容写入 stdout。
• 请为 Agent 配置专用 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