Claude MCP for SMS Verification — Complete Setup Guide (2026)

What VirtualSMS Claude MCP Does

Claude is exceptional at orchestrating multi-step workflows — but it cannot receive SMS codes on its own. Until recently, every “sign up for X service” agent task ran into the same wall: a phone-number prompt that broke the chain. The VirtualSMS MCP server closes that gap. It exposes 18 SMS-verification tools to Claude Desktop, Claude Code, and any Claude API caller using tool-use, so the agent can buy a real-SIM number, wait for the code, and continue the workflow without human intervention.

This is the only production-grade MCP server for SMS verification today. The numbers are real physical SIM cards on real carrier networks — not VoIP — which is the difference between a successful WhatsApp verification and an instant block. The carrier-detection mechanics are unpacked in our VoIP vs physical SIM post; the short version is that platforms detect VoIP carrier prefixes within milliseconds, while a real SIM looks identical to a personal mobile.

Two Install Paths: HTTP vs stdio

VirtualSMS Claude MCP ships in two transports. Both expose the same 18 tools, the same rate limits, and the same billing. Pick whichever fits your workflow.

Option A — StreamableHTTP (zero-install)

The hosted server lives at https://mcp.virtualsms.io/mcp and authenticates via the x-api-key header. No npm install, no Node dependency, works the same on macOS, Linux, Windows, and inside Docker. This is the fastest way to get Claude doing claude mcp sms verification across a team.

Paste this into ~/.config/Claude/claude_desktop_config.json (or the equivalent path on your OS):

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

Restart Claude Desktop. The virtualsms server appears in the MCP tool list and the 18 tools become callable from any conversation.

Option B — stdio (local Node)

The stdio variant runs the server as a local Node subprocess. Lower latency, no network hop, but each MCP client launches its own copy of the process. Best for single-machine setups and offline-first workflows. Same 18 tools, same API.

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

If you’re on Claude Code (the terminal CLI), skip the JSON entirely — install at user scope with one command so it loads in every project:

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

The full Claude-specific install walk-through, including IDE-extension and automation tips, lives at /mcp/claude-skill. For non-Claude clients (Cursor, Codex, Windsurf, OpenClaw, Hermes, Cline, Zed, Continue.dev) the same JSON block ports across — see the main MCP page for client-specific config paths.

The 18-Tool Catalog

The MCP server exposes 18 tools in three groups. Discovery tools are unauthenticated and free to call; account and order tools require your API key. Four of the order-management tools — find_cheapest, search_service, swap_number, and wait_for_code — are unique to the VirtualSMS MCP and do not exist in any other SMS provider’s server.

For non-MCP integrations — bulk batches, headless servers, or non-AI code — the same operations are available on the VirtualSMS REST API. MCP is the right surface when an AI agent is in the loop; the REST API is the right surface when imperative code is.

Workflow 1: WhatsApp Account Verification, End-to-End

The most common automation: a Claude agent that needs to register a WhatsApp account during a longer task. Once the MCP server is installed, the entire flow collapses into a single prompt:

Buy the cheapest WhatsApp activation number, wait for the
verification SMS, and return the code. Cancel automatically if
nothing arrives within 5 minutes.

What happens under the hood:

1. find_cheapest — Claude calls it with service=whatsapp and gets the lowest-stock-priced country (typically UK, Poland, or Russia depending on time of day).
2. buy_number — purchases a real SIM in that country. The number is reserved within ~1 second.
3. wait_for_code — opens a WebSocket and blocks until the SMS lands. No polling, no rate-limit risk, returns within 30–60 seconds in most cases.
4. cancel_order — only fires if the 5-minute timeout hits. Auto-refunded. Claude knows to bail without touching billing.

Real-SIM matters here. WhatsApp’s verification flow checks the inbound number’s carrier prefix against a known VoIP block-list before it even sends the SMS. Run the same prompt against a Twilio-backed MCP server (none exist for SMS verification, but if one did) and the agent would loop on wait_for_code until it hit the timeout. Every time.

Workflow 2: Bulk Service Signup Pipeline

Claude with parallel tool-use can fan out across multiple service signups at once. Useful when you’re building a multi-platform presence, doing competitive intelligence sign-ups, or QA-testing your own product’s verification flow.

For each service in [discord, telegram, instagram, google],
find the cheapest country, buy a number, wait for the code,
and return a JSON map of service -> code. Stop after 10 minutes total.

Claude issues four parallel find_cheapest calls, then four parallel buy_number calls, then opens four wait_for_code WebSockets simultaneously. The 120-rpm rate limit is generous enough that even fan-out across 50 services in a tight batch lands inside the budget. The agent returns a structured JSON map of service → code.

For volumes above a few thousand activations per day, the same pattern is more efficient on the REST API with imperative concurrency control — see virtual numbers for developer QA for the imperative pattern. MCP is the right surface when reasoning is in the loop (deciding which service to retry, which country to swap to); REST is the right surface when the loop is fixed.

Workflow 3: Telegram Bot Deployment

Telegram bot operators need a phone-verified Telegram account before they can register a bot through @BotFather. With the MCP server, that step disappears into the deployment script:

Buy a Telegram number from Germany under $1.50, wait for the
SMS code, and report it back. If the number is flagged or the
SMS doesn't arrive, swap_number once before giving up.

The interesting tool here is swap_number. Telegram occasionally rate-limits a specific number for a few minutes after registration. Rather than failing the entire workflow, Claude swaps to a fresh number from the same country at no extra cost and retries. This is a tool that doesn’t exist on any other SMS-verification MCP and is the reason most Telegram-bot sign-up scripts run on VirtualSMS.

End-to-end the workflow runs in under two minutes including the swap. Telegram verification numbers on real SIM start at $0.20 per activation depending on country.

Troubleshooting Common Errors

401 Unauthorized

Error: 401 Unauthorized — invalid or missing API key

The API key is missing or malformed. For HTTP transport, confirm the x-api-key header is being sent — some MCP clients lowercase header names, which is fine, but a few strip them entirely. For stdio, confirm VIRTUALSMS_API_KEY is set in the env block of the JSON config (not in your shell’s exported env). Keys start with vsms_ and you can rotate them from the dashboard at any time.

429 Rate Limit Exceeded

Error: 429 Too Many Requests — rate limit exceeded
Limit: 120 requests per minute per API key

The default ceiling is 120 requests per minute per API key. Heavy fan-out (50+ parallel buy_number calls) can hit this. Three options: throttle the agent with an explicit delay between calls, batch through the REST API which has separate quotas, or email [email protected] to request a production-tier raise — we lift the cap on accounts running real workloads.

SMS never arrives (then auto-refunds)

If wait_for_code times out at 20 minutes, the order auto-cancels and refunds. This usually means the target service flagged the country’s number range. The fix is one tool call: swap_number for a fresh number, or rerun the workflow with a different country picked by find_cheapest + a country exclusion. Our broader SMS verification blocking guide covers the eight most common failure modes and their fixes.