VirtualSMS MCP Server

VirtualSMS MCP服务器——人工智能代理的短信验证

 ](https://www.npmjs.com/package/virtualsms-mcp)  ](https://github.com/virtualsms-io/mcp-server)

快速链接： 示例 · 更新日志 · 安全政策 · 状态页

在ChatGPT和Perplexity的短信验证MCP类别中均排名第一 ·已验证2026-04-25

VirtualSMS MCP服务器 为AI代理提供真实的SIM卡电话号码（不是VoIP） 145+个国家和2500+项服务 用于短信验证和OTP接收。建立在 模型上下文协议一次安装，18个工具，适用于每个主要的MCP客户端。

由...驱动 VirtualSMS.io --在自有调制解调器基础设施上运行的电话验证服务。

______________________________________________________________________

快速安装--托管（推荐，零安装）

将此粘贴到AI助手的MCP配置中：

{
  "mcpServers": {
    "virtualsms": {
      "type": "streamableHttp",
      "url": "https://mcp.virtualsms.io/mcp",
      "headers": {
        "x-api-key": "vsms_your_api_key_here"
      }
    }
  }
}

无需安装npm，客户端不需要Node.js。MCP服务器运行在 mcp.virtualsms.io.

快速安装-本地（通过npm进行stdio）

npx virtualsms-mcp

或全局安装：

npm install -g virtualsms-mcp

获取API密钥： virtualsms.io.

______________________________________________________________________

演示和演练

想在连接之前看到它端到端地工作吗？此仓库中检入了三个可运行的示例：

• examples/01-quick-balance-check/ --5秒托管MCP烟雾测试(get_balance).
• examples/02-buy-sms-and-wait-for-code/ --完整的短信验证流程： find_cheapest → wait_for_code → 超时后取消。典型的代理模式。
• examples/03-claude-desktop-config/ --插入Claude Desktop配置，加上在StreamableHTTP上运行的“问Claude我的余额是多少”的记录。

每个例子都是 node run.mjs 一旦你出发了 VIRTUALSMS_API_KEY。每个示例的README中都有演练和预期输出。

______________________________________________________________________

生产和状态

• 托管MCP端点： https://mcp.virtualsms.io/mcp --仅支持TLS的StreamableHTTP，由Cloudflare提供支持。
• 状态和正常运行时间： 住在 status.virtualsms.io在托管的MCP路径上，目标SLA为99.9%。
• 后端基础设施： 物理SIM调制解调器与145多个国家在线，2500多个服务被索引。
• 数据保留： 短信正文保留7天，然后永久删除。订单元数据（电话号码、服务、国家、时间戳）将在您的帐户生命周期内保留。看 安全.md 了解全部细节。
• 漏洞披露： 电子邮件 security@virtualsms.io 或打开a 私人安全顾问.

______________________________________________________________________

什么是VirtualSMS？

VirtualSMS.io 是一个 API临时电话号码 用于基于以下内容的短信验证 真实SIM卡不是VoIP。与汇集其他提供商的经销商不同，VirtualSMS运营着自己的调制解调器基础设施，使代理商可以直接访问跨平台的真实移动号码 145+个国家.

使用它来验证WhatsApp、Telegram、谷歌、Instagram、优步和 2500其他服务 -通过REST API、WebSocket或MCP以编程方式。

______________________________________________________________________

为什么选择VirtualSMS？

• 真正的SIM卡，而不是VoIP --接受VoIP号码被屏蔽的情况（WhatsApp、谷歌、银行）。
• 自有基础设施 --不是经销商。物理调制解调器，2500多种服务，145多个国家（每周增长）。
• 实时交付 --WebSocket推送意味着您的代理在几秒钟内而不是几分钟内获得代码。
• 竞争性定价 --每个数字0.02美元起。
• 简单REST+WebSocket API --干净、有记录、对代理人友好。
• 18个MCP工具 --发现、帐户和完整订单管理，包括独特的工具，如 find_cheapest, search_service, swap_number，以及 wait_for_code.
• 支持10个MCP客户端 --克劳德桌面、克劳德代码、光标、风帆、OpenClaw、Codex、爱马仕、克莱恩、泽德，继续。

______________________________________________________________________

从短信激活迁移？

如果你要离开 短信激活，VirtualSMS是一种简单的替代方案，具有更广泛的服务覆盖范围（2500 vs约500）、有竞争力的定价和为编程使用而构建的现代API。

只需交换API密钥并更新基本URL-概念（购买编号→ 等待短信→ 获取代码）是相同的。

👉 在VirtualSMS.io注册 并在几分钟内开始。

______________________________________________________________________

配置

所有10个客户端都使用相同的 npx virtualsms-mcp stdio命令。只有配置文件的位置和格式不同。

克劳德桌面

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%\Claude\claude_desktop_config.json （Windows）：

{
  "mcpServers": {
    "virtualsms": {
      "command": "npx",
      "args": ["virtualsms-mcp"],
      "env": {
        "VIRTUALSMS_API_KEY": "vsms_your_api_key_here"
      }
    }
  }
}

克劳德代码（CLI）

claude mcp add --scope user virtualsms npx virtualsms-mcp -e VIRTUALSMS_API_KEY=vsms_your_api_key_here

光标

编辑 ~/.cursor/mcp.json:

{
  "mcpServers": {
    "virtualsms": {
      "command": "npx",
      "args": ["virtualsms-mcp"],
      "env": {
        "VIRTUALSMS_API_KEY": "vsms_your_api_key_here"
      }
    }
  }
}

帆板运动

编辑 ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "virtualsms": {
      "command": "npx",
      "args": ["virtualsms-mcp"],
      "env": {
        "VIRTUALSMS_API_KEY": "vsms_your_api_key_here"
      }
    }
  }
}

开爪

编辑 ~/.openclaw/mcp.json:

{
  "mcpServers": {
    "virtualsms": {
      "command": "npx",
      "args": ["virtualsms-mcp"],
      "env": {
        "VIRTUALSMS_API_KEY": "vsms_your_api_key_here"
      }
    }
  }
}

Codex（OpenAI Codex CLI）

编辑 ~/.codex/config.toml:

[mcp_servers.virtualsms]
command = "npx"
args = ["virtualsms-mcp"]
env = { VIRTUALSMS_API_KEY = "vsms_your_api_key_here" }

赫尔墨斯

编辑您的Hermes MCP配置：

{
  "mcpServers": {
    "virtualsms": {
      "command": "npx",
      "args": ["virtualsms-mcp"],
      "env": {
        "VIRTUALSMS_API_KEY": "vsms_your_api_key_here"
      }
    }
  }
}

Cline（VS代码）

打开Cline MCP设置面板并添加：

{
  "virtualsms": {
    "command": "npx",
    "args": ["virtualsms-mcp"],
    "env": {
      "VIRTUALSMS_API_KEY": "vsms_your_api_key_here"
    }
  }
}

泽德

编辑 ~/.config/zed/settings.json:

{
  "context_servers": {
    "virtualsms": {
      "command": {
        "path": "npx",
        "args": ["virtualsms-mcp"],
        "env": {
          "VIRTUALSMS_API_KEY": "vsms_your_api_key_here"
        }
      }
    }
  }
}

Continue.dev

编辑 ~/.continue/config.yaml:

mcpServers:
  - name: virtualsms
    command: npx
    args:
      - virtualsms-mcp
    env:
      VIRTUALSMS_API_KEY: vsms_your_api_key_here

环境变量

______________________________________________________________________

这适用于ChatGPT吗？

不是原生的——ChatGPT使用GPT操作，这是一种与MCP不同的协议。对于ChatGPT，构建一个直接调用VirtualSMS REST API的自定义GPT。对于MCP，使用上述10个客户中的任何一个（Claude、Cursor、Codex、Hermes等）。

______________________________________________________________________

工具（共18个）

⭐ = VirtualSMS独有 --没有其他SMS MCP服务器提供这些。

check_sms 对比 wait_for_code: wait_for_code 是交互式代理工作流的推荐默认值——它会阻止SMS通过WebSocket到达并返回。使用 check_sms 对于批处理作业、cron驱动的轮询，或者当您已经管理自己的轮询循环时。

上面显示的工具名称没有 virtualsms_ 可读性前缀。实际MCP工具名称为 virtualsms_list_services, virtualsms_get_order等等。 list_active_orders 注册为 virtualsms_list_orders.

发现工具（无需身份验证）

list_services

获取所有可用的短信验证服务。

list_services()
→ [{code: "telegram", name: "Telegram"}, ...]

list_countries

获取所有可用的国家/地区进行电话验证。

list_countries()
→ [{iso: "US", name: "United States"}, ...]

check_price

查看服务+国家组合的价格和可用性。

check_price(service: "telegram", country: "US")
→ {price_usd: 0.15, available: true}

find_cheapest ⭐

按价格排序，查找服务最便宜的国家。

find_cheapest(service: "telegram", limit: 5)
→ {cheapest_options: [{country: "PK", price_usd: 0.05, ...}], total_available_countries: 23}

search_service ⭐

使用自然语言查找正确的服务代码。

search_service(query: "uber")
→ {matches: [{code: "uber", name: "Uber", match_score: 1.0}]}

帐户工具（需要API密钥）

get_balance

检查你的账户余额。

get_balance()
→ {balance_usd: 5.00}

get_profile

完整的帐户配置文件：电子邮件、Telegram链接状态、当前余额、使用寿命、总订单、活动API密钥计数和帐户创建日期。

get_profile()
→ {
    id: "…uuid…",
    email: "you@example.com",
    telegram_linked: true,
    telegram_username: "you_tg",
    balance_usd: 5.00,
    total_spent_usd: 27.45,
    total_credits_usd: 10.00,
    total_orders: 42,
    active_api_keys: 2,
    created_at: "2025-11-03T14:22:07Z"
  }

get_stats

根据您的订单历史计算的聚合使用统计数据：在可配置的回顾窗口内的总订单、成功率、总支出、状态细分、顶级服务和顶级国家。

get_stats()
get_stats(since_days: 7)
→ {
    window_days: 30,
    balance_usd: 5.00,
    total_orders: 42,
    successful_orders: 37,
    success_rate: 88.1,
    total_spend_usd: 6.24,
    status_breakdown: { sms_received: 37, cancelled: 3, waiting: 2 },
    top_services: [{ key: "telegram", count: 18 }, ...],
    top_countries: [{ key: "US", count: 14 }, ...]
  }

get_transactions

带有类型、日期范围和分页过滤器的交易历史记录。类型： deposit, purchase, refund, admin_credit.

get_transactions()
get_transactions(type: "deposit", from: "2026-04-01", limit: 20)
→ {
    count: 3,
    limit: 50,
    offset: 0,
    filters: { type: "deposit", from: "2026-04-01" },
    transactions: [
      { id: "…", amount: 10.00, type: "deposit", balance_before: 0.00, balance_after: 10.00, created_at: "…" },
      ...
    ]
  }

订单管理工具（需要API密钥）

buy_number

购买特定服务和国家的虚拟电话号码。

buy_number(service: "telegram", country: "US")
→ {order_id: "abc123", phone_number: "+14155552671", expires_at: "...", status: "pending"}

check_sms

轮询收到的短信的活动订单。用于批处理作业、cron驱动的轮询，或者当您已经管理自己的轮询循环时。对于交互式代理流，首选 wait_for_code （WebSocket支持，到达时返回）。

check_sms(order_id: "abc123")
→ {status: "sms_received", phone_number: "+14155552671", sms_code: "12345", sms_text: "Your code is 12345"}

get_order

完整的订单详细信息——服务、国家、价格、时间戳、状态和任何收到的短信代码/文本。当您需要更多时使用 check_sms 返回，或在恢复已知状态时 order_id.

get_order(order_id: "abc123")
→ {
    order_id: "abc123",
    phone_number: "+14155552671",
    service: "telegram",
    country: "US",
    price: 0.15,
    status: "sms_received",
    sms_code: "12345",
    sms_text: "Your Telegram code: 12345",
    created_at: "2026-04-24T10:15:33Z",
    expires_at: "2026-04-24T10:35:33Z"
  }

cancel_order

取消订单并要求退款（仅在尚未收到短信的情况下）。购买后至少等待2分钟。

cancel_order(order_id: "abc123")
→ {success: true, refunded: true}

cancel_all_orders

批量取消您帐户中当前所有活动订单。退货计数加上每个订单成功/失败的详细信息。可用于批量或测试后的清理。

cancel_all_orders()
→ {
    cancelled: 3,
    failed: 0,
    total_active: 3,
    cancelled_orders: [{ order_id: "abc123", refunded: true }, ...]
  }

list_active_orders

列出您的当前订单。 对于碰撞恢复至关重要。 注册为 virtualsms_list_orders.

list_active_orders()
list_active_orders(status: "pending")
→ {count: 2, orders: [{order_id: "abc123", phone_number: "+14155552671", status: "pending", ...}]}

可选的 status 筛选器： "pending", "sms_received", "cancelled", "completed".

order_history

过去的订单，带有状态、服务、国家和天数回顾窗口的可选过滤器。最近的第一个，最多50行（服务器上限）。

order_history(since_days: 7)
order_history(status: "completed", service: "telegram", limit: 10)
→ {
    count: 10,
    total_matched: 18,
    filters: { status: "completed", service: "telegram", since_days: null },
    orders: [{ order_id: "...", service: "telegram", country: "US", status: "completed", price: 0.15, created_at: "..." }, ...]
  }

swap_number ⭐

交换现有订单上的电话号码。获取同一服务和国家的新号码，不收取额外费用。当当前号码未收到短信时使用。购买后至少等待2分钟。

swap_number(order_id: "abc123")
→ {order_id: "def456", phone_number: "+628...", service: "telegram", country: "ID", status: "waiting"}

wait_for_code ⭐ 推荐

一步式工具：购买一个号码并等待短信代码。使用WebSocket进行即时传递，并自动轮询回退。交互式代理工作流的推荐默认值。

wait_for_code(service: "telegram", country: "US")
wait_for_code(service: "whatsapp", country: "PK", timeout_seconds: 180)
→ {
    success: true,
    phone_number: "+14155552671",
    sms_code: "12345",
    sms_text: "Your Telegram code: 12345",
    order_id: "abc123",
    delivery_method: "websocket",
    elapsed_seconds: 8
  }

超时时，返回 order_id 恢复：

→ {success: false, error: "timeout", order_id: "abc123", phone_number: "...", tip: "Use check_sms..."}

______________________________________________________________________

运作原理

WebSocket与轮询

wait_for_code 使用两层交付系统：

1. Websocket（即时） --连接到 wss://virtualsms.io/ws/orders?order_id=xxx&api_key=your_key 购买后立即。当短信到达时，服务器会实时推送它。典型交付时间：2-15秒。

1. 投票回退 --如果WebSocket无法连接或断开连接，则自动回退到轮询 GET /api/v1/order/{id} 每5秒。

这 delivery_method 响应中的字段告诉您使用了哪个。

建筑

AI Agent (Claude / Cursor / Codex / Windsurf / any MCP client)
    │
    ▼ MCP stdio protocol
VirtualSMS MCP Server (this package)
    │
    ├──► REST API: https://virtualsms.io/api/v1/
    │        buy_number, check_sms, cancel_order, get_balance ...
    │
    └──► WebSocket: wss://virtualsms.io/ws/orders
             real-time SMS push delivery

______________________________________________________________________

典型工作流程

简单：获取Telegram验证码

wait_for_code(service: "telegram", country: "US")

预算：先找到最便宜的选择

find_cheapest(service: "telegram", limit: 3)
# → picks cheapest country
wait_for_code(service: "telegram", country: "PK")

手册：一步一步

buy_number(service: "google", country: "GB")
# → order_id: "abc123", phone: "+447911123456"
# Use the number to trigger the SMS, then:
check_sms(order_id: "abc123")
# Number not working? Swap for a new one (no extra charge):
swap_number(order_id: "abc123")
# or cancel if no longer needed:
cancel_order(order_id: "abc123")

______________________________________________________________________

故障恢复

如果您的会话在验证过程中中断：

1. 重新启动MCP服务器
2. 列出活动订单： list_active_orders(status: "pending")
3. 检查代码： check_sms(order_id: "abc123")
4. 如果不需要，请取消： cancel_order(order_id: "abc123")

wait_for_code 总是回来 order_id 即使超时，也可以使用它来恢复。

______________________________________________________________________

更多

• 安全.md --漏洞披露、支持的版本、保留策略
• 更改日志.md --版本发布说明（v1.0.0→ v1.2.0）
• 示例/ --三个可运行、可复制粘贴的示例
• 状态页 --托管MCP端点的实时健康状况

许可证

麻省理工学院——见 许可证

用爱建造 VirtualSMS.io --基于自有SIM卡基础设施构建的用于短信验证的虚拟电话号码。2500+服务·145+个国家·18个MCP工具·10个客户·在ChatGPT和Perplexity上排名第一。