@esimfly/mcp — eSIMfly MCP server

Give your AI assistant hands on the eSIMfly Business API. With this Model Context Protocol server, Claude, Cursor, ChatGPT and other MCP clients can search eSIM plans with your wholesale prices, check balances and usage, diagnose "no data" problems from live network data — and, if you enable it, place orders and top-ups with an explicit confirmation step.

• Read-only by default. Nothing can spend your balance unless you opt in.
• Two-step writes. Every write tool returns a preview (what, cost, balance) until called with confirm: true.
• Built on the official @esimfly/sdk — signing, retries and error codes handled.
• Ships two prompts: the complete integration guide and an eSIM diagnosis workflow.

Docs: https://docs.esimfly.net · Credentials: Business Dashboard → Settings → API Keys.

Hosted server (no install)

Prefer not to run anything locally? eSIMfly hosts this same server at https://mcp.esimfly.net/mcp. Add it as a remote MCP server in Claude.ai, ChatGPT, Claude Code (claude mcp add --transport http esimfly https://mcp.esimfly.net/mcp), Cursor or VS Code and sign in with your eSIMfly business account — OAuth 2.1, no keys to paste, write tools opt-in on the consent screen. Details: https://docs.esimfly.net/docs/mcp-server

Local install

The server runs locally over stdio; your API key never leaves your machine.

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 / other MCP clients

.cursor/mcp.json (or the client's equivalent):

{
  "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

Enable write tools

Add "ESIMFLY_MCP_ALLOW_WRITES": "true" to env. Without it the ordering, top-up, cancel, suspend, SMS and webhook tools are not even registered.

Try it

• "Find the cheapest 5 GB plan for Turkey and tell me my margin at €9.99."
• "Which of my eSIMs are active and below 200 MB?"
• "ICCID 8948010010036785060 says no data — diagnose it." (uses the diagnose_esim prompt)
• "Set up webhooks for installed / status / low-data events at https://my.app/hooks." (write tool, previews first)
• "Build me a Node.js integration." (uses the esimfly_integration_guide prompt)

Tools

| Tool | What it does | Mode | |---|---|---| | search_packages | Catalogue search by destination / type with your cost price | read | | get_balance | Account (or enterprise) balance | read | | list_esims | Your eSIMs with status, data left, validity | read | | get_esim_usage | Stored usage for one eSIM (cheap) | read | | get_esim_live_status | Live status from the network: install state, last network, device, usage | read (expensive) | | get_network_events | Last 7 days of attach / data-session events, wrong-network flag | read | | get_usage_report | Daily usage by country and operator (up to 90 days) | read | | list_orders / get_order | Order history and one order with its eSIM | read | | get_topup_packages | Top-up options for one eSIM | read | | get_webhook_settings | Webhook URL, events, recent deliveries | read | | create_order | Buy eSIMs — preview → confirm: true + idempotency key | write | | topup_esim | Add data to an eSIM — preview shows package and cost | write | | cancel_esim | Cancel an unused eSIM and refund to balance | write (destructive) | | suspend_esim / activate_esim | Block / restore network access | write | | send_sms | Text the device holding the eSIM | write | | set_webhook | Configure webhook URL and events | write |

Prompts: esimfly_integration_guide (optional stack), diagnose_esim (iccid).

Safety model

• Read-only unless ESIMFLY_MCP_ALLOW_WRITES=true.
• Write tools are two-step: a call without confirm returns a preview and makes no mutable API call; create_order additionally requires the idempotency_key from its own preview, so an agent cannot place the same order twice.
• Tool annotations mark reads as readOnlyHint and cancel/suspend as destructiveHint, so hosts that ask for user approval on risky tools do so.
• The server never logs credentials and never writes to stdout except the MCP protocol.
• Give the agent a dedicated API key with the smallest rate limits you are comfortable with, and rotate it from the dashboard if in doubt.

Configuration

| Variable | Required | Description | |---|---|---| | ESIMFLY_ACCESS_CODE | yes | API access code (esf_…) | | ESIMFLY_SECRET_KEY | yes | API secret key (sk_…) | | ESIMFLY_MCP_ALLOW_WRITES | no | true to register write tools | | ESIMFLY_BASE_URL | no | Override the API base URL |

Embedding

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

Releasing (maintainers)

Bump version in package.json, server.json and MCP_VERSION in src/server.ts, add a CHANGELOG entry, push, then publish a GitHub Release tagged vX.Y.Z — the workflow publishes to npm with Trusted Publishing (OIDC), and the MCP Registry entry is republished automatically afterwards (GitHub OIDC, no tokens).

Support

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