VoidMob MCP

VoidMob MCP

移动代理、非 VoIP 短信验证、专属号码和全球 eSIM——通过 30 个可供 AI Agent 直接调用的工具提供，还包括简短指南（资源）和引导式提示词。

npx -y @voidmob/mcp

设置

1. 在 https://dashboard.voidmob.com/developers/api-keys 生成 API 密钥（密钥为 32 个字符的机密字符串，以 vmk_live_ 为前缀），并在 https://dashboard.voidmob.com/wallet 使用加密货币充值。
2. 将 MCP 添加到你的客户端（见下方代码片段）。将密钥设为 VOIDMOB_API_KEY。
3. 可选：使用所有者控制设置每笔订单限额和会话预算。

各客户端和 Agent 运行时的分步指南：voidmob.com/mcp 和 voidmob.com/integrations。

Claude Code

作为插件安装（一次安装即可包含 MCP 服务和技能；对话框会将你的密钥保存为机密，并提供沙盒、只读和支出限额选项）：

/plugin marketplace add voidmobcom/voidmob-plugin
/plugin install voidmob@voidmob

或仅安装 MCP 服务：

claude mcp add voidmob -s user -e VOIDMOB_API_KEY=vmk_live_... -- npx -y @voidmob/mcp

-s user 会使该服务在每个项目中都可用；密钥放在 -e 之后、-- 之前。同一插件也可安装到 Codex 和 Gemini CLI：请参阅 voidmob-plugin。

Cursor

添加到 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "voidmob": {
      "command": "npx",
      "args": ["-y", "@voidmob/mcp"],
      "env": { "VOIDMOB_API_KEY": "vmk_live_..." }
    }
  }
}

Claude Desktop

一键安装包。 从 最新的 GitHub 版本下载 voidmob-mcp.mcpb 并打开（或将其拖入 Claude Desktop，或使用 Settings > Extensions > Advanced > Install Extension）。Claude Desktop 会要求你填写设置：API 密钥（安全存储）、沙盒模式、只读、每笔订单上限和会话预算（参见所有者控制）。也可以使用 npm run pack:mcpb 自行构建。

或者使用配置文件。 打开 Settings > Developer > Edit Config（macOS 上为 ~/Library/Application Support/Claude/claude_desktop_config.json，Windows 上为 %APPDATA%\Claude\claude_desktop_config.json）并添加：

{
  "mcpServers": {
    "voidmob": {
      "command": "npx",
      "args": ["-y", "@voidmob/mcp"],
      "env": { "VOIDMOB_API_KEY": "vmk_live_..." }
    }
  }
}

VS Code

添加到 .vscode/mcp.json（VS Code 会提示你输入一次密钥并安全存储）：

{
  "inputs": [
    { "type": "promptString", "id": "voidmob-api-key", "description": "VoidMob API key (vmk_live_...)", "password": true }
  ],
  "servers": {
    "voidmob": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@voidmob/mcp"],
      "env": { "VOIDMOB_API_KEY": "${input:voidmob-api-key}" }
    }
  }
}

Windsurf (Devin Desktop)

从 Cascade 面板菜单中打开 MCP 配置（Open MCP config file）。当前版本的 Devin Desktop 将其存放在 ~/.config/devin/mcp_config.json（Windows：%APPDATA%\devin\mcp_config.json）；更名之前的 Windsurf 版本使用 ~/.codeium/windsurf/mcp_config.json。添加：

{
  "mcpServers": {
    "voidmob": {
      "command": "npx",
      "args": ["-y", "@voidmob/mcp"],
      "env": { "VOIDMOB_API_KEY": "vmk_live_..." }
    }
  }
}

Codex CLI

codex mcp add voidmob --env VOIDMOB_API_KEY=vmk_live_... -- npx -y @voidmob/mcp

或者添加到 ~/.codex/config.toml（由 Codex CLI、IDE 扩展和 ChatGPT 桌面应用共用）：

[mcp_servers.voidmob]
command = "npx"
args = ["-y", "@voidmob/mcp"]
env = { VOIDMOB_API_KEY = "vmk_live_..." }

Gemini CLI

添加到 ~/.gemini/settings.json，并在 shell 中导出 VOIDMOB_API_KEY（除非服务的 env 中列出了这些变量，否则 Gemini CLI 会对 MCP 服务隐藏名称类似密钥的变量）：

{
  "mcpServers": {
    "voidmob": {
      "command": "npx",
      "args": ["-y", "@voidmob/mcp"],
      "env": { "VOIDMOB_API_KEY": "$VOIDMOB_API_KEY" }
    }
  }
}

OpenClaw

将 VOIDMOB_API_KEY=vmk_live_... 放入 ~/.openclaw/.env，然后：

openclaw mcp set voidmob '{"command":"npx","args":["-y","@voidmob/mcp"],"env":{"VOIDMOB_API_KEY":"${VOIDMOB_API_KEY}"}}'
openclaw mcp doctor voidmob --probe

或者使用 Agent 技能。指南：voidmob.com/integrations/openclaw。

Hermes Agent

将 VOIDMOB_API_KEY=vmk_live_... 放入 ~/.hermes/.env，并添加到 ~/.hermes/config.yaml：

mcp_servers:
  voidmob:
    command: "npx"
    args: ["-y", "@voidmob/mcp"]
    env:
      VOIDMOB_API_KEY: "${VOIDMOB_API_KEY}"

或者使用 Agent 技能。指南：voidmob.com/integrations/hermes-agent。

Pi

pi mcp add voidmob --env VOIDMOB_API_KEY='${VOIDMOB_API_KEY}' -- npx -y @voidmob/mcp
pi mcp list

单引号会让 ${VOIDMOB_API_KEY} 保持为引用，Pi 会从你的 shell 中读取它。指南：voidmob.com/integrations/pi-coding-agent。

Grok Bot

1. 在 Bot 的 Secrets 中，添加名为 VOIDMOB_API_KEY 的密钥，并将你的密钥设为其值。
2. 在聊天中发送：Read https://voidmob.com/skill.md and follow it. My VoidMob API key is in the VOIDMOB_API_KEY secret.

该技能会在 Bot 的计算机上使用 curl 调用 REST API，并按名称读取密钥。另一种方式是尝试运行 npx -y @voidmob/mcp 的 Command 类型自定义 MCP 服务；xAI 的文档建议需要密钥的服务使用远程 HTTPS，因此如果服务无法读取密钥，请使用该技能。切勿在聊天中粘贴密钥本身。指南：voidmob.com/integrations/grok-bot。

资金如何运作

• 预付余额。 所有费用都从你的 USD 余额中扣除，你可以在控制面板中使用加密货币充值。MCP 无法为余额充值。API 密钥没有单独的消费上限：你的余额就是限额，因此只在账户中保留你愿意让 Agent 使用的金额，并考虑使用本地的所有者控制。
• 由你批准价格。 搜索工具会显示实时价格。每次购买、续订、充值和付费复用都需要 max_price_cents：即 Agent 向你展示并经你批准的价格。如果当前价格更高，则不会扣费，工具会返回新价格，以便 Agent 再次征求你的同意；绝不会按你未看到的价格购买。每次购买都会立即从余额中扣款，每项结果都会显示扣除的金额。
• 重试不会重复扣费。 每次购买都会携带一个幂等键。如果连接中断，此 MCP 服务会使用相同的密钥重试一次，API 不会因此重复扣费。
• 结果不确定时， 工具会说明购买可能已经成功。再次购买前，请检查 list_orders、相应的获取工具或 get_account。
• 未收到短信时，短信验证不收费。 一个号码最多可保持开放 15 分钟，并可接收多个验证码。如果始终未收到验证码，系统会自动退款（状态为 cancelled）。少数例外情况：标记为不可退款的服务会以 expired 状态结束，且不会退款。收到任何短信前，你也可以取消并获得全额退款；频繁取消可能会导致短信购买暂时暂停。
• 长期租用可在购买后 60 分钟内取消并获得全额退款。
• 专用号码按月计费，且无法取消；关闭自动续订后，号码会在月底到期。
• eSIM一经发放，就无法通过 MCP 取消。如果误购且从未安装，请联系支持团队。
• 无法配置的代理会自动退款。

所有者控制

供安装 MCP 服务的人员使用的可选安全设置。在实时模式和沙盒模式下均适用，任何一项设置导致拒绝都不会产生费用。

Env var	Effect
VOIDMOB_READ_ONLY=1	完全不注册任何会花费金钱或更改内容的工具。Agent 只能搜索价格和查看订单，不能执行其他操作。
VOIDMOB_MAX_ORDER_CENTS=2500	在发出任何请求前，拒绝 max_price_cents 超过此值（此处为 $25）的购买、续订、充值或付费复用。如果一次续订的费用更高，也会拒绝开启自动续订。
VOIDMOB_BUDGET_CENTS=5000	此 MCP 服务进程的累计支出上限（此处为 $50）。MCP 服务会统计每笔购买的扣费；如果结果不明确（例如连接中断或购买仍在处理中），则按完整的 max_price_cents 计入。可能导致超出上限的购买会被拒绝，并且无法开启自动续订（续订费用会在会话之外的稍后时间扣除）。**这是每个会话的安全网，不是账户限额：**MCP 服务重启后会重置，且无法查看在其他地方进行的购买。
VOIDMOB_TOOLSETS=sms,esim	仅加载这些工具组，让 Agent 处理更少的上下文：sms、numbers（专用号码）、esim、proxy。账户、订单和地理位置工具始终启用。

get_account 会显示当前生效的限额以及剩余预算。值格式错误时，MCP 服务会报错并停止，而不是忽略该值。

等待短信验证码

调用 rent_number 后，使用 wait_seconds 调用 get_rental（最长 120 秒）。MCP 服务会轮询，间隔为 2、3、5、8 秒，之后每隔 10-15 秒轮询一次；收到验证码、15 分钟窗口关闭或等待时间结束时，会立即返回，并附上最新的短信。提供进度令牌的客户端会收到进度通知；取消请求会停止等待。短信文本会以围栏形式显示为不可信数据：它来自短信发送者，绝不是指令。

资源和提示词

MCP 服务会将简短指南作为 MCP 资源提供，内容取自随软件包附带的 Agent 技能：voidmob://guides/money-rules、voidmob://guides/sms、voidmob://guides/proxies（HTTP/SOCKS5，以及用于设置国家、城市和粘性会话的用户名语法）、voidmob://guides/esim、voidmob://guides/dedicated-numbers 和 voidmob://guides/errors。

提示词（支持这些功能的客户端中的斜杠命令），每条都会在购买前确认价格：

• get_verification_code（服务）：租用号码并等待验证码。
• setup_mobile_proxy（国家、用途）：选择并购买移动代理，然后获取连接详情。
• buy_travel_esim（目的地、天数、流量_GB）：查找、购买并安装旅行 eSIM。

只读 MCP 服务不提供提示词，而 VOIDMOB_TOOLSETS 只会保留已加载工具组对应的提示词。

无需密钥即可试用（沙盒）

VOIDMOB_SANDBOX=1 npx -y @voidmob/mcp

使用内存模拟数据启动，并提供 $500 的虚拟余额。所有工具都使用模拟数据运行。重启后状态会重置。

Agent 技能

对于任何能使用 shell 和 curl 的 Agent（无论是否使用 MCP，包括 Claude Code、Codex、Cursor、OpenClaw、Hermes 及其他 Agent Skills 客户端），skills/voidmob 都是一个 Agent Skills SKILL.md 文件，通过 REST API 教授相同的流程：余额检查、先获取报价再确认购买、幂等重试、短信验证码、专用号码、代理和 eSIM。它是纯 Markdown 文件，不含脚本。它会从 VOIDMOB_API_KEY 读取密钥；请在 Agent 的环境或密钥存储中设置该变量，切勿将密钥写入技能文件。

最快的方法：告诉你的 Agent 阅读 https://voidmob.com/skill.md 并按其说明操作。

# skills.sh CLI (Claude Code, Codex, Cursor, OpenClaw, Hermes and more)
npx skills add voidmobcom/voidmob-mcp --skill voidmob
# or from voidmob.com
npx skills add https://voidmob.com --skill voidmob

# Hermes Agent (use the full well-known address, not the voidmob.com/skill.md short link,
# so the skill's reference files resolve)
hermes skills install well-known:https://voidmob.com/.well-known/skills/voidmob
# or
hermes skills install voidmobcom/voidmob-mcp/skills/voidmob

# OpenClaw
npx skills add voidmobcom/voidmob-mcp --skill voidmob -a openclaw -g

# Pi (skill only, from the npm package)
pi install npm:@voidmob/mcp

在 Hermes 中，还要将密钥列入 ~/.hermes/config.yaml 的 terminal.env_passthrough，这样技能中的 curl 调用才能获取该密钥。

配置

环境变量	用途	必填
VOIDMOB_API_KEY	从控制面板获取的 Bearer 密钥	实时模式
VOIDMOB_SANDBOX	设置为 1 以启用模拟数据模式	否
VOIDMOB_READ_ONLY	1 = 不使用任何会产生费用或更改任何内容的工具（所有者控制）	否
VOIDMOB_MAX_ORDER_CENTS	单笔订单限额，单位为美分	否
VOIDMOB_BUDGET_CENTS	单次会话的支出上限，单位为美分	否
VOIDMOB_TOOLSETS	要加载的工具组：sms、numbers、esim、proxy（默认：全部）	否
VOIDMOB_DEBUG	设置为 1，将请求记录到 stderr	否
VOIDMOB_BASE_URL	覆盖 API 主机（高级选项；必须使用 https://，仅 localhost 可使用纯 http://）	否

工具

六个领域共提供 30 个工具。每个工具都会返回文本以及符合其声明的 outputSchema 的 structuredContent。

账户（1）

工具	描述
get_account	余额、速率限制和账户 ID

SMS（7）

工具	描述
search_sms_services	列出服务及其价格
rent_number	租用美国号码：一次性验证（15 分钟，未收到 SMS 可退款）或长期租用；需要提供 max_price_cents
get_rental	查看状态、最新验证码和收到的消息；wait_seconds 会等待验证码
cancel_rental	取消验证（收到任何 SMS 前）或长期租用（60 分钟内），并全额退款
reuse_number	免费或付费重复使用先前验证所用的号码（付费时需要提供 max_price_cents）
re_rent_rental	重新租用已到期长期租用的号码；需要提供 max_price_cents
toggle_auto_renew	开启或关闭自动续费（适用于租用号码和专用号码）

专用号码（3）

工具	描述
search_dedicated_countries	国家、月费和库存
purchase_dedicated_number	购买可用于所有服务的私人月租号码；需要提供 max_price_cents
get_dedicated_number	状态和收到的 SMS，以及解析出的验证码

eSIM（5）

工具	描述
search_esim_plans	查找全球数据套餐
purchase_esim	购买套餐；需要提供 max_price_cents
get_esim_status	查看所有套餐的状态、安装详情（LPA 字符串）和数据使用量
topup_esim	浏览充值选项，或使用 max_price_cents 购买充值
get_esim_qr	获取作为内嵌图片的激活二维码

代理（12）

工具	描述
search_proxies	列出移动代理（共享）和专用代理套餐，以及专用代理库存
purchase_proxy	购买移动代理或专用代理；需要提供 max_price_cents
get_proxy_status	查看状态、使用量、到期时间、自动续费、续费和充值价格，以及可直接粘贴的连接 URL
rotate_proxy_ip	将专用代理切换到新的 IP
renew_proxy	按代理续费价格延长到期时间；需要提供 max_price_cents
set_proxy_auto_renew	开启或关闭专用代理的自动续费
topup_proxy	为移动代理增加流量；需要提供 max_price_cents
regenerate_proxy_password	更换网关密码，或使用 list_id 更换某个列表的登录信息
list_proxy_lists	列出按地理位置定位的子池
create_proxy_list	创建拥有独立登录信息的按地理位置定位子池，或使用 network 创建 IP 白名单身份验证
update_proxy_list	更改子池的名称、地理位置、轮换设置或格式（无法更改 IP 白名单）
delete_proxy_list	移除子池

发现与历史记录（2）

工具	描述
get_geo	按国家/地区、省区、城市和 ISP 层级筛选目标
list_orders	查看 SMS 验证和租用、专用号码、eSIM 与代理；支持按类型筛选 status，并使用 cursor 翻页

示例提示词

给我租一个美国号码，用于 Telegram 验证

查找一个覆盖整个欧洲、至少有 5GB 流量且有效期为两周的 eSIM 套餐

显示我的活跃代理

为 esim_xxx 充值 5GB

在多个进程间共享密钥

同时运行的多个 MCP 客户端（Claude Code + Cursor + Desktop）共享同一个账户级速率限制。大量并行使用可能触发 RATE_LIMITED；请退避后重试。

---

网站 · 文档 · MCP · API 参考 · MIT 许可证