@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

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

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

support@esimfly.net · https://docs.esimfly.net