Skip to main content
Glama
kakha13

esim-mcp

by kakha13
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

esim-mcp

npm version npm downloads CI MCP Registry License: MIT

An MCP server for travel eSIM plans. It lets Claude, Cursor, and any other Model Context Protocol client search travel eSIM data plans by country, compare prices, and work out the cheapest way to stay connected across a multi-country trip.

Ask "what is the cheapest eSIM for two weeks in Japan and South Korea?" and get real plans with real prices, not a guess.

esim-mcp is built and maintained by CheapereSIM, and returns CheapereSIM pricing. It covers 190+ destinations across 8 regions.

What you can ask

Once installed, these all work in plain language:

  • "What is the cheapest eSIM for Japan?"

  • "I am travelling to Japan, South Korea and Taiwan for three weeks. What should I buy?"

  • "Is there a single eSIM that covers all of Southeast Asia?"

  • "Which countries does that regional plan actually cover?"

  • "Show me unlimited data eSIM plans for Turkey."

  • "How much data is left on my eSIM?" (needs a token)

The interesting one is the multi-country case. A regional eSIM that covers your whole trip is sometimes cheaper than buying a local eSIM in each country, and sometimes it is not. plan_trip prices both and tells you which wins.

Related MCP server: firsty-mcp

Setup

Add this to your MCP client configuration:

{
  "mcpServers": {
    "esim": {
      "command": "npx",
      "args": ["-y", "esim-mcp"]
    }
  }
}

No API key, no account, and no configuration are required to search destinations and compare plans. Set CHEAPERESIM_API_TOKEN only if you also want the two account tools.

Example: planning a multi-country trip

Asking plan_trip for three weeks across Japan, South Korea and Taiwan, with at least 10GB:

Option 1 - one plan covering everything, $34.58:
Asia (12 areas) 10GB 30Days: 10 GB for 30 days - $34.58 - covers 12 countries
  https://cheaperesim.com/multi-country-esim?package=2488&utm_source=mcp&utm_medium=ai&utm_campaign=esim-mcp

Option 2 - one local plan per country, $17.52 total:
Japan 10GB 30Days: 10 GB for 30 days - $8.76
  https://cheaperesim.com/esim/japan?package=339&utm_source=mcp&utm_medium=ai&utm_campaign=esim-mcp
South Korea 10GB 30Days: 10 GB for 30 days - $8.76
  https://cheaperesim.com/esim/south-korea?package=345&utm_source=mcp&utm_medium=ai&utm_campaign=esim-mcp
No local plan available for: TW.

Recommended: option 1, since option 2 does not cover: TW.

That is real output against live pricing, not an illustration. It is also the case worth understanding: buying local is half the price, and it is still the wrong answer, because Taiwan is sold only inside regional plans. A price comparison that stopped at the cheaper number would leave you without service for a third of the trip.

The server prints each buy_url exactly as the API returns it, so the links above are the ones you would get.

Tools

Tool

Description

Requires token

search_destinations

Find countries CheapereSIM sells eSIM plans for, by full or partial name.

No

list_plans

List eSIM plans for one country, cheapest first.

No

plan_trip

Work out the cheapest way to stay connected across several countries.

No

get_plan_coverage

List every country a regional or global plan covers.

No

list_popular_destinations

List the destinations travellers buy eSIMs for most often.

No

list_my_esims

List the eSIMs on the configured CheapereSIM account.

Yes

get_esim_usage

Show how much data is left on one eSIM.

Yes

list_my_esims and get_esim_usage are only registered when CHEAPERESIM_API_TOKEN is set. Without a token, the server exposes the first five tools only, so a model never sees a tool it cannot call.

Environment variables

Variable

Default

Purpose

CHEAPERESIM_API_BASE

https://cheaperesim.com

Base URL of the CheapereSIM API

CHEAPERESIM_API_TOKEN

unset

API token for the two account tools; omit to run in read-only lookup mode

CHEAPERESIM_TIMEOUT_MS

10000

Request timeout in milliseconds

Keep CHEAPERESIM_API_BASE on https. The token is sent as a bearer header, so an http override would put it on the wire in cleartext.

Getting a token

Create a token at cheaperesim.com/dashboard/api-tokens. Tokens are read-only: they can list your eSIMs and their usage, but they cannot buy a plan, change your profile, or delete your account. Treat one like a password and revoke it if it leaks.

FAQ

What is an eSIM? A digital SIM your phone downloads instead of a plastic card you swap in. Most phones sold since about 2018 support one, so you can buy mobile data for a country before you land and skip roaming charges.

Which countries can I search? 190+ destinations across Europe, Asia, North and South America, Africa, Oceania and the Middle East, plus regional and global plans that span many countries at once. Use search_destinations to check a specific one.

Does this cost anything to install? No. The server and the five lookup tools are free and need no account. You only pay if you decide to buy a plan on cheaperesim.com.

Is a regional eSIM cheaper than buying one per country? It depends on the trip, which is the whole reason plan_trip exists. For two neighbouring countries a pair of local plans often wins; across four or five, a regional plan usually does. The tool prices both and shows the difference.

Does it work with anything other than Claude? Yes. It speaks the Model Context Protocol over stdio, so any MCP client can run it, including Cursor and custom agents built on the MCP SDKs.

Can it buy a plan for me? No, by design. Every tool is read-only. Plans come back with a link, and the purchase happens in your browser on cheaperesim.com.

Development

npm install
npm test
npm run build

npm run typecheck type-checks the tests as well as the source. CI runs the build, the typecheck, and the suite on Node 20 and 22.

License

MIT. See LICENSE.

Available Tools

5 tools
get_plan_coverageA

List every country a regional or global plan covers. Takes the group_id from a plan returned by plan_trip or list_plans. Local plans have a null group_id and cover only their own country.

ParametersJSON Schema
NameRequiredDescriptionDefault
group_idYesThe plan group id, from a plan's group_id field

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden. It discloses a key behavioral trait: local plans have null group_id and cover only their own country, implying the tool is for regional/global plans. The verb 'List' also implies a read-only operation. It doesn't detail error handling or output format, but for a simple listing tool this is adequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the main purpose, and no extraneous information. Every word earns its place, making it highly efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with a single parameter and no output schema, the description is complete: it states what it does, where the input comes from, and an important edge case (local plans). The return type (list of countries) is implied by the purpose statement, so no further detail is needed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already covers the parameter with 100% description coverage, but the tool description adds value by explaining where the group_id comes from (a plan returned by plan_trip or list_plans) and the null group_id caveat. This goes beyond the schema's basic field description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists countries covered by a plan, using a specific verb ('List') and resource ('every country a regional or global plan covers'). It distinguishes from sibling tools like list_plans (which lists plans) and search_destinations, making the purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explains where to obtain the group_id (from plan_trip or list_plans) and clarifies that local plans with null group_id are not applicable. This gives clear context for when to use the tool, though it doesn't explicitly mention alternatives or exclusions beyond the local plan case.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_plansA

List eSIM plans for one country, cheapest first. Use plan_trip instead when the user is visiting more than one country.

ParametersJSON Schema
NameRequiredDescriptionDefault
daysNoOnly plans lasting at least this many days
limitNoHow many plans to return, default 20
countryYesISO country code such as JP, or a slug such as south-korea
min_data_gbNoOnly plans with at least this much data. Unlimited plans always qualify

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden. It discloses the 'cheapest first' ordering and the single-country limitation, which are behavioral details not in the schema. However, it does not mention result size limits (the 'limit' param) or potential error behavior, so it is not fully transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two compact sentences with no filler. The first sentence states the primary action and ordering; the second gives a conditional alternative. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is sufficient for a simple list tool: it specifies the single-country scope, ordering, and a sibling alternative. While there is no output schema and no mention of pagination or return format, the limited complexity of the operation and full schema parameter coverage make this adequately complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already explains all parameters (country, days, limit, min_data_gb). The description adds no extra parameter meaning beyond the single-country scope already reflected in the schema, thus baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('List') and resource ('eSIM plans'), scopes to 'one country', and adds ordering ('cheapest first'). It also distinguishes from the sibling tool plan_trip for multi-country trips, making it unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when NOT to use: 'Use plan_trip instead when the user is visiting more than one country.' This provides a clear exclusion and names the alternative tool, giving strong usage guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

plan_tripA

Work out the cheapest way to stay connected across several countries. Compares one regional plan covering the whole trip against buying a local plan per country, and says which is cheaper. Use this whenever the user names more than one destination.

ParametersJSON Schema
NameRequiredDescriptionDefault
daysNoTrip length in days
countriesYesTwo-letter ISO country codes, for example ["JP", "KR", "TW"]. This tool does not accept country names or slugs: call search_destinations first to get the code.
min_data_gbNoMinimum data per plan, in GB. Unlimited plans always qualify

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must carry the full burden. It discloses the core comparison behavior and the fact that it returns a cheaper option, but does not elaborate on output format, data sources, assumptions, or limitations. This is adequate but not rich.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise: two sentences that front-load the core purpose and then provide a direct usage guideline. Every sentence adds value, with no redundant or fluffy content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is relatively simple: three parameters, no output schema, no annotations. The description covers the tool's purpose, its comparison logic, and when to use it, which is sufficient for a basic understanding. It lacks detail on return value structure but does mention 'says which is cheaper,' offering minimal output guidance. This is complete enough given the tool's moderate complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema provides 100% coverage with detailed descriptions for all three parameters, so the baseline is 3. The description does not add significant parameter-level meaning beyond what the schema already states; it merely references the multi-country aspect. Therefore, a 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with a specific verb ('work out') and resource ('the cheapest way to stay connected across several countries'). It distinguishes itself from siblings by focusing on multi-country trip cost comparison, contrasting a single regional plan versus per-country local plans, and explicitly says it outputs which is cheaper.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides a clear usage condition: 'Use this whenever the user names more than one destination.' This gives explicit when-to-use guidance. However, it does not explicitly mention when NOT to use or name alternative tools for single-destination scenarios, so it falls short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_destinationsA

Find countries CheapereSIM sells eSIM plans for, by full or partial name. Use this when the user names a place and you need its country code before looking up plans. Do not use it to compare prices or list plans: use list_plans for a single country, or plan_trip for several.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesCountry name or partial name, for example "jap" or "south kor"

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full transparency burden. It discloses that it matches by full or partial name and that the purpose is to retrieve a country code, but it does not specify the return format (e.g., a list of countries with codes), behavior for no matches, or any pagination/limitations. This leaves room for inference, making it only minimally viable.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences, each serving a distinct role: stating the purpose, giving the when-to-use scenario, and listing alternatives with explicit not-to-use cases. There is no redundant or filler language.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with a single parameter and no annotations or output schema, the description covers the core context effectively: what it does, when to use it, and what it returns (implied country codes). It could explicitly state the output structure or edge cases like no results, but the simplicity of the tool makes the current description nearly complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already describes the query parameter as 'Country name or partial name, for example "jap" or "south kor"', giving 100% coverage. The description repeats the 'full or partial name' concept without adding new semantics, so it does not exceed the baseline for high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Find countries CheapereSIM sells eSIM plans for, by full or partial name.' It specifies the verb (find), the resource (countries), and the method (full or partial name), making it distinct from sibling tools that list plans or compare prices.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit usage guidance: 'Use this when the user names a place and you need its country code before looking up plans.' It also includes exclusions and alternatives: 'Do not use it to compare prices or list plans: use list_plans for a single country, or plan_trip for several.'

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 5 tool updatesv0.1.0
    • First observedget_plan_coverage
    • First observedlist_plans
    • First observedlist_popular_destinations
    • First observedplan_trip
    • First observedsearch_destinations
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.4/5.0

Scored across 5 tools

Disambiguation5/5

Each tool has a clearly distinct purpose with explicit usage guidance in descriptions. search_destinations is for country codes, list_plans for single-country plans, list_popular_destinations for suggestions without a destination, get_plan_coverage for plan coverage details, and plan_trip for multi-country comparisons. No two tools overlap in a way that would cause confusion.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern in snake_case: search_, list_, list_, get_, plan_. The verbs are imperative and the objects are clear, making the naming uniform and predictable.

Tool Count5/5

With 5 tools, the server is well-scoped for its domain. Each tool covers a distinct aspect of eSIM planning: destination lookup, plan listing, popular suggestions, coverage details, and multi-country trip optimization. The count is neither sparse nor overwhelming.

Completeness5/5

The tool surface covers the full discovery-to-decision workflow: finding destinations, listing plans, considering popular options, understanding coverage, and comparing multi-country scenarios. There are no obvious dead ends—every user query about eSIM plans can be addressed with these tools.

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • firsty-mcp

    aoyn1xw
    -
    license
    Not graded
    quality
    Not graded
    maintenance
    An MCP server that wraps the Firsty telecom API, allowing AI agents to manage eSIMs, data plans, phone numbers, and network coverage.
    -

Appeared in Searches