{
  "markdown": "# @roamzy/mcp-server\n\nMCP server for [Roamzy](https://roamzy.io) — buy and manage a global eSIM\nthrough Claude Desktop, Cursor, Continue, Cline, Windsurf, Zed, or any other\n[Model Context Protocol](https://modelcontextprotocol.io) client. Anonymous\nflow by default: no account required to use it.\n\n**Agents don't just buy — they earn.** A built-in referral pays you 20% of every\npayment from anyone you refer — a human user *or* another AI agent — forever. Even\nanonymous agents earn from day one, no signup. That's the distribution flywheel:\nan agent that earns has a reason to tell the next agent.\n\n> One eSIM for 193 countries. Pay per actual MB used. USDT or USDC on your\n> preferred network. No packages. No expiry. No subscription.\n\n[![npm version](https://img.shields.io/npm/v/@roamzy/mcp-server?color=cb3837&logo=npm&logoColor=white)](https://www.npmjs.com/package/@roamzy/mcp-server)\n[![npm downloads](https://img.shields.io/npm/dm/@roamzy/mcp-server?color=cb3837&logo=npm&logoColor=white&label=downloads)](https://www.npmjs.com/package/@roamzy/mcp-server)\n[![GitHub stars](https://img.shields.io/github/stars/roamzy-io/mcp-server?style=flat&logo=github&color=181717)](https://github.com/roamzy-io/mcp-server/stargazers)\n[![MCP](https://img.shields.io/badge/MCP-compatible-blue)](https://modelcontextprotocol.io)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)\n[![Node](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org)\n[![Glama score](https://glama.ai/mcp/servers/roamzy-io/mcp-server/badges/score.svg)](https://glama.ai/mcp/servers/roamzy-io/mcp-server)\n[![MCP Badge](https://lobehub.com/badge/mcp/roamzy-io-mcp-server)](https://lobehub.com/mcp/roamzy-io-mcp-server)\n\n---\n\n## What it does\n\nThis MCP server lets an agent (running in any MCP-compatible client) call the\nRoamzy HTTP API on the user's behalf. Sample conversation in Claude Desktop:\n\n> **User:** I'm going to Thailand for a week, buy me an eSIM.\n>\n> **Claude:** Roamzy — one universal eSIM, works in 193 countries. Billed per\n> MB at the local rate, no packages, no expiry. For Thailand the rate is\n> ~$1.43/GB. Which stablecoin / network do you want to pay with?\n> (USDT on TRON, BSC, Polygon, Optimism, Arbitrum, TON — or USDC on Solana,\n> BSC, Polygon, Optimism, Arbitrum.) Minimum top-up is $20 USDT.\n>\n> **User:** USDC on Solana, $20.\n>\n> **Claude:** Order created. eSIM number 2040XXXXXX. Pay here: [pay-link].\n> After ~1 minute on Solana, I'll fetch your QR.\n> ❗ Save this recovery URL so you can return to this eSIM from another\n> Claude chat: [claim-link].\n>\n> *User pays $20 USDC.*\n>\n> **Claude:** Paid. Here's your activation QR — open Settings → Cellular →\n> Add eSIM and scan it with your phone camera. [QR PNG attached]\n\nThe server doesn't run a backend itself — it's a thin client to\n`https://roamzy.io/api/v1/*`, mapped 1:1 to MCP tools.\n\n---\n\n## Install\n\nAdd this to your MCP client's configuration (e.g. `~/Library/Application\nSupport/Claude/claude_desktop_config.json` for Claude Desktop on macOS):\n\n```json\n{\n  \"mcpServers\": {\n    \"roamzy\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@roamzy/mcp-server\"]\n    }\n  }\n}\n```\n\nRestart your MCP client. The first authed tool call will mint an anonymous\nRoamzy account automatically — no signup required.\n\n### Alternative: install from a hosted tarball\n\nIf you can't reach the npm registry, want to pin a pre-release, or prefer to\nfetch a specific version directly from Roamzy's CDN, swap the args to a URL:\n\n```json\n\"args\": [\"-y\", \"https://roamzy.io/mcp/roamzy-mcp-latest.tgz\"]\n```\n\nBoth forms run the same code — the npm registry path is the recommended\ndefault because it integrates with `npm view`, version pinning, and MCP\nregistries (Smithery, modelcontextprotocol/servers, etc.).\n\n### Optional environment variables\n\n| Variable                  | Default                            | Purpose                                                                                                |\n|---------------------------|------------------------------------|--------------------------------------------------------------------------------------------------------|\n| `ROAMZY_API_TOKEN`        | _(unset → anonymous mode)_         | Use a pre-existing API token from `/dashboard/settings` instead of an anonymous account.               |\n| `ROAMZY_ENABLE_PURCHASE`  | `false` _(but `true` in anon mode)_| When using a non-anonymous token, opt-in flag required to expose purchase tools.                       |\n| `ROAMZY_API_BASE`         | `https://roamzy.io/api/v1`         | Override for staging / self-hosted backends.                                                           |\n\n---\n\n## Tools\n\n### Public (no auth required)\n\n| Tool                       | Purpose                                                                                  |\n|----------------------------|------------------------------------------------------------------------------------------|\n| `roamzy_status`            | Service status + agent-pause flags. Call before any purchase attempt.                    |\n| `roamzy_list_countries`    | Reference list of all 193 supported countries with per-MB rates.                         |\n| `roamzy_country_detail`    | Per-MB rate for one country.                                                             |\n| `roamzy_estimate`          | Reference calc: «how many USDT would N MB cost in country X».                            |\n| `roamzy_support`           | Official support channels + recovery procedure. Call instead of web-searching.           |\n| `roamzy_payment_options`   | Currently-enabled stablecoins + networks (live from NowPayments). Call before order.     |\n\n### Account-scoped (anonymous or token)\n\n| Tool                       | Purpose                                                                                  |\n|----------------------------|------------------------------------------------------------------------------------------|\n| `roamzy_me`                | Current Roamzy account info (auto-mints anonymous account on first call).                |\n| `roamzy_list_esims`        | The account's eSIMs with MSISDN, status, balance.                                        |\n| `roamzy_get_esim`          | One eSIM's activation details (QR payload, LPA URI). Generate the QR PNG locally.        |\n| `roamzy_order_status`      | Poll a pending order: `waiting → confirming → finished`.                                 |\n| `roamzy_referral`          | The account's referral link, earnings, and payout state. Read-only.        |\n\n### Purchase (anonymous or token + `ROAMZY_ENABLE_PURCHASE=true`)\n\n| Tool                       | Purpose                                                                                  |\n|----------------------------|------------------------------------------------------------------------------------------|\n| `roamzy_create_order`      | Mint a new eSIM and fund it. Min top-up $20 USDT. Requires `pay_currency` from options.  |\n\nEach tool returns structured JSON. Tool descriptions (visible via\n`tools/list`) encode the agent contract — when to call each tool, what to\nsurface to the user, what to keep internal.\n\n---\n\n## Anonymous flow\n\nWhen the MCP server starts without `ROAMZY_API_TOKEN`, the first authed call\nsends `POST /api/v1/anon-session` (no auth) to mint a fresh anonymous Roamzy\naccount. The server caches the returned token in-process (never written to\ndisk) and uses it for subsequent calls.\n\nThe response also includes a `claim_url` — a magic-link that lets the user\nlater attach this anonymous account to a permanent Google or Telegram\nidentity. Once attached, the eSIM, balance, and history become visible from\n`/dashboard/esims` on the web.\n\n**Important:** the anonymous token lives only in this MCP server process. If\nthe user closes their MCP client (e.g. quits Claude Desktop) without saving\n`claim_url`, the access path is lost — the eSIM itself keeps working, but\nthe user can't see or manage it from a new session. The recovery procedure\n(operator-mediated via support) is described in the `roamzy_support` tool\nresponse.\n\nAnonymous accounts have conservative daily / monthly spending caps and a\ncool-off period that gates large transactions; exact thresholds are shown to\nthe user in the dashboard once they claim.\n\n---\n\n## Security model\n\n- **No filesystem access.** The server only makes HTTP calls.\n- **No child processes.**\n- **No environment scan** beyond explicit `ROAMZY_*` variables.\n- **Outbound traffic only to `https://roamzy.io`** (override via\n  `ROAMZY_API_BASE` if you self-host).\n- **Purchase tools** are registered only in anonymous mode or with\n  `ROAMZY_ENABLE_PURCHASE=true`.\n- **Per-token spending caps** with cool-off period + big-transaction\n  threshold; configurable per token in `/dashboard/settings`.\n- **Service status honoured.** When `roamzy_status` reports\n  `purchases_paused=true`, the agent must back off.\n- **No telemetry.** The server doesn't phone home except to call the\n  configured API base.\n\nSee [`SECURITY.md`](./SECURITY.md) for the disclosure policy.\n\n---\n\n## Build from source\n\n```bash\ngit clone https://github.com/roamzy-io/mcp-server.git\ncd mcp-server\npnpm install\npnpm build\n```\n\nOutput: a single-file ESM bundle at `dist/index.js` (self-contained,\nexecutable via Node 20+).\n\nTo produce a tarball for distribution:\n\n```bash\npnpm build:tgz\n# → dist/roamzy-mcp-server-<version>.tgz\n```\n\n---\n\n## Links\n\n- Website: [https://roamzy.io](https://roamzy.io)\n- API docs: [https://roamzy.io/api/v1/docs](https://roamzy.io/api/v1/docs)\n- For agents: [https://roamzy.io/agents.html](https://roamzy.io/agents.html)\n- Long-form for AI engines: [https://roamzy.io/llms-full.txt](https://roamzy.io/llms-full.txt)\n- Support: [@roamzy_support_bot](https://t.me/roamzy_support_bot) or `support@roamzy.io`\n- Security: `roamzy.agent@gmail.com` ([SECURITY.md](./SECURITY.md))\n\n---\n\n## License\n\n[MIT](./LICENSE) — © 2026 Artur. The Roamzy name and brand are trademarks of\nthe Roamzy service operator and are not licensed under MIT.\n",
  "bytes": 10079,
  "sha": "ab0d2ab51a1d1d36f90f2dd03fdc4e9d6a6a1ffc88ac90ea66d091a8c57eed47",
  "repo_slug": "roamzy-io/mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_roamzy_io_mcp_server_e1465c2e/readme"
}