roamzy-io

@roamzy/mcp-server

Roamzy 的 MCP 服务——通过 Claude Desktop、Cursor、Continue、Cline、Windsurf、Zed 或任何其他模型上下文协议客户端，购买和管理全球 eSIM。默认采用匿名流程：无需账户即可使用。

Agent 不仅能购买，还能赚取收益。 内置的推荐计划会让你从每位受邀者的每笔付款中永久获得 20% 的收益——无论对方是人类用户，还是另一个 AI Agent。匿名 Agent 从第一天起也能赚钱，无需注册。这就是分发飞轮：能赚钱的 Agent 自然有动力告诉下一个 Agent。

一张 eSIM，覆盖 193 个国家和地区。按实际使用的 MB 计费。可在你首选的网络上使用 USDT 或 USDC 支付。无套餐，无过期时间，无订阅。

---

功能

此 MCP 服务可让 Agent（在任何兼容 MCP 的客户端中运行）代表用户调用 Roamzy HTTP API。以下是在 Claude Desktop 中的对话示例：

用户： 我要去泰国待一周，帮我买一张 eSIM。

Claude： Roamzy——一张通用 eSIM，可在 193 个国家和地区使用。按 MB 以当地费率计费，无套餐，无过期时间。泰国的费率约为每 GB 1.43 美元。你想使用哪种稳定币／网络付款？ （TRON、BSC、Polygon、Optimism、Arbitrum、TON 上的 USDT，或 Solana、BSC、Polygon、Optimism、Arbitrum 上的 USDC。）最低充值金额为 20 美元 USDT。

用户： 用 Solana 上的 USDC，充值 20 美元。

Claude： 订单已创建。eSIM 号码 2040XXXXXX。请在此付款：[pay-link]。 在 Solana 上等待约 1 分钟后，我会获取你的二维码。 ❗ 请保存此恢复 URL，以便你从另一个 Claude 对话返回这张 eSIM：[claim-link]。

用户支付 20 美元 USDC。

Claude： 已付款。这是你的激活二维码——打开“设置”→“蜂窝网络”→“添加 eSIM”，然后用手机摄像头扫描。[附有二维码 PNG]

此服务自身不运行后端——它是一个轻量客户端，将 https://roamzy.io/api/v1/* 一对一映射为 MCP 工具。

---

安装

将以下内容添加到 MCP 客户端的配置中（例如，在 macOS 上使用 Claude Desktop 时，配置文件为 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "roamzy": {
      "command": "npx",
      "args": ["-y", "@roamzy/mcp-server"]
    }
  }
}

重启 MCP 客户端。首次调用需要身份验证的工具时，系统会自动创建匿名 Roamzy 账户——无需注册。

替代方式：从托管的 tarball 安装

如果无法访问 npm 注册表、想固定使用预发布版本，或希望直接从 Roamzy CDN 获取特定版本，可以将 args 替换为一个 URL：

"args": ["-y", "https://roamzy.io/mcp/roamzy-mcp-latest.tgz"]

两种方式运行的都是相同代码——推荐默认使用 npm 注册表方式，因为它支持 npm view、固定版本以及 MCP 注册表（Smithery、modelcontextprotocol/servers 等）。

可选环境变量

变量	默认值	用途
ROAMZY_API_TOKEN	(未设置 → 匿名模式)	使用 /dashboard/settings 中已有的 API 令牌，而非匿名账户。
ROAMZY_ENABLE_PURCHASE	false (但在匿名模式下为 true)	使用非匿名令牌时，需要启用此选项才能开放购买工具。
ROAMZY_API_BASE	https://roamzy.io/api/v1	用于覆盖暂存环境／可自托管后端。

---

工具

公开（无需身份验证）

工具	用途
roamzy_status	服务状态及 Agent 暂停标志。进行任何购买前请先调用。
roamzy_list_countries	包含所有 193 个受支持国家及每 MB 费率的参考列表。
roamzy_country_detail	某个国家的每 MB 费率。
roamzy_estimate	参考计算：“在 X 国，N MB 需要多少 USDT”。
roamzy_support	官方支持渠道及恢复流程。请调用此工具，而不要搜索网页。
roamzy_payment_options	当前启用的稳定币及网络（来自 NowPayments 的实时数据）。下单前请调用。

账户范围（匿名或使用令牌）

工具	用途
roamzy_me	当前 Roamzy 账户信息（首次调用时会自动创建匿名账户）。
roamzy_list_esims	账户的 eSIM，包括 MSISDN、状态和余额。
roamzy_get_esim	一张 eSIM 的激活详情（QR 载荷、LPA URI）。请在本地生成 QR PNG。
roamzy_order_status	轮询待处理订单：waiting → confirming → finished。
roamzy_referral	账户的推荐链接、收益和付款状态。只读。

购买（匿名或使用令牌 + ROAMZY_ENABLE_PURCHASE=true）

工具	用途
roamzy_create_order	创建一张新 eSIM 并为其充值。最低充值金额为 20 USDT。需要提供选项中的 pay_currency。

每个工具都会返回结构化 JSON。工具描述（可通过 tools/list 查看）定义了 Agent 的约定——何时调用各个工具、向用户展示哪些内容，以及哪些内容应保留在内部。

匿名流程

当 MCP 服务在没有 ROAMZY_API_TOKEN 的情况下启动时，首次经过身份验证的调用会发送 POST /api/v1/anon-session（无身份验证），以创建一个全新的 Roamzy 匿名账户。服务会在进程内缓存返回的令牌（绝不写入磁盘），并将其用于后续调用。

响应还包含一个 claim_url——一个魔法链接，用户之后可通过它将此匿名账户关联到永久的 Google 或 Telegram 身份。关联后，用户便可在网页的 /dashboard/esims 中查看 eSIM、余额和历史记录。

**重要提示：**匿名令牌仅存在于此 MCP 服务进程中。如果用户关闭 MCP 客户端（例如退出 Claude Desktop）时没有保存 claim_url，访问途径就会丢失——eSIM 本身仍可使用，但用户无法在新会话中查看或管理它。roamzy_support 工具的响应中介绍了恢复流程（由运营方通过支持服务协助处理）。

匿名账户设有较为保守的每日／每月消费上限，以及限制大额交易的冷却期；用户领取账户后，可在控制面板中查看具体阈值。

---

安全模型

• **不访问文件系统。**服务只进行 HTTP 调用。
• 不创建子进程。
• 除明确指定的 ROAMZY_* 变量外，不扫描环境变量。
• 仅向 https://roamzy.io 发送出站流量（自托管时可通过 ROAMZY_API_BASE 覆盖）。
• 仅在匿名模式下或设置 ROAMZY_ENABLE_PURCHASE=true 时注册购买工具。
• 每个令牌均设有消费上限，并配有冷却期和大额交易阈值；可在 /dashboard/settings 中按令牌配置。
• **遵从服务状态。**当 roamzy_status 报告 purchases_paused=true 时，Agent 必须暂停操作。
• **不收集遥测数据。**除调用配置的 API 基址外，服务不会主动连接其他地址。

披露政策请参阅 SECURITY.md。

---

从源代码构建

git clone https://github.com/roamzy-io/mcp-server.git
cd mcp-server
pnpm install
pnpm build

输出：位于 dist/index.js 的单文件 ESM 打包文件（自包含，可通过 Node 20+ 执行）。

要生成用于分发的 tarball：

pnpm build:tgz
# → dist/roamzy-mcp-server-<version>.tgz

---

链接

• 网站：https://roamzy.io
• API 文档：https://roamzy.io/api/v1/docs
• 面向 Agent：https://roamzy.io/agents.html
• 面向 AI 引擎的长篇资料：https://roamzy.io/llms-full.txt
• 支持：@roamzy_support_bot 或 [email protected]
• 安全：[email protected]（SECURITY.md）

---

许可证

MIT — © 2026 Artur。Roamzy 名称和品牌是 Roamzy 服务运营方的商标，不受 MIT 许可证授权。