VirtualSMS MCP Server

Quick links: Quickstart · Why VirtualSMS · What you can build · Tools · Questions · Examples · Changelog · Security policy · Status

VirtualSMS is an account verification platform for developers and AI agents. It combines one-time SMS verification, dedicated number rentals, matching-country proxies and private cloud browser sessions behind one API, one MCP server and one prepaid balance.

Infrastructure for AI agents that need real-world phone verification.

The numbers are carrier-issued mobile numbers, backed by real physical SIM cards on carrier networks, not VoIP, which is why they pass the line-type checks that reject VoIP numbers at signup.

From one prepaid balance you can:

• receive one-time SMS codes from $0.05
• rent dedicated numbers from 1 to 30 days
• buy matching-country residential, mobile and datacenter proxies
• launch private cloud browser sessions that work alongside your number and proxy (beta)

All four work together from one prepaid balance, one API and one dashboard. Use only the pieces you need, or combine them into a single verification workflow.

Most providers solve one piece of the verification workflow. VirtualSMS combines numbers, rentals, proxies and cloud browser sessions behind one API, SDKs and an MCP server, so you use only the pieces you need or combine them into one workflow.

VirtualSMS can be used by individuals manually, integrated into applications with SDKs and APIs, or driven by AI agents through MCP. Use the platform through a REST API, official SDKs for Node, Python, PHP, Ruby and .NET, a hosted MCP server, or automation tools like n8n.

This server exposes that platform to any MCP client. Built for AI agents. Designed for AI-agent workflows. Works with Claude Code, Claude Desktop, Cursor, Windsurf and every MCP-compatible client, with no wrapper code to write.

---

Quickstart

Paste this into your MCP client’s config. Nothing to install, no Node.js required on the client:

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

Get an API key at virtualsms.io. Then ask your agent:

“Buy me a Telegram number in the cheapest country and wait for the code.”

Prefer to run it locally over stdio instead:

npx virtualsms-mcp

---

Why VirtualSMS

Verifying an account should not mean stitching together numbers from one provider, proxies from another, and browser sessions from a third: multiple accounts, multiple balances and APIs, and support spread across vendors. VirtualSMS brings those pieces together behind one balance, one API and one MCP server.

VirtualSMS combines all three under one account, and gives you one way to drive them:

• Carrier-issued mobile numbers. Backed by real physical SIM cards, not VoIP, so they resolve as mobile at signup.
• Matching-country proxies. Residential, mobile and datacenter pools, so the number and the IP agree.
• Private cloud browser sessions. Beta.
• REST API. Documented at virtualsms.io/docs.
• Hosted MCP server. This repo, live at https://mcp.virtualsms.io/mcp.
• One prepaid balance. Verification, rentals and proxies all draw from it.

Everything below expands on those six.

---

What you can build

Concrete jobs this server does today. Every one is a plain-English request your agent turns into tool calls:

Runnable versions of the first two live in examples/.

---

Client setup

Every client runs the same npx virtualsms-mcp stdio command. Only the file location and format differ. The hosted config above works anywhere streamableHttp is supported and is the recommended path.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

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

Quit and reopen Claude Desktop. A drop-in config plus a worked transcript lives in examples/03-claude-desktop-config/.

Does this work with ChatGPT?

Yes, via ChatGPT’s Developer Mode. Open Settings, turn on Developer mode, then add https://mcp.virtualsms.io/mcp as a custom connector (Plus, Pro, Business, Enterprise and Edu plans; not available on the free tier). Setup is a URL paste rather than a config file, so it differs from the client setups above. ChatGPT only connects to remote MCP servers over SSE or streaming HTTP, so use the hosted endpoint, not the local stdio command. The REST API is still there if you would rather build a custom GPT or Action instead.

---

Configuration

---

Tools

40 tools by default. Set VIRTUALSMS_ENABLE_SESSIONS=1 to expose 3 more.

Tool names are shown below without the virtualsms_ prefix for readability. The real wire names are prefixed: virtualsms_create_order, virtualsms_get_sms, and so on.

---

Typical workflows

Get a verification code

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

wait_for_sms(order_id: "abc123", timeout_seconds: 180)
→ {success: true, code: "12345", delivery_method: "websocket", elapsed_seconds: 8}

Find the cheapest country first

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

create_order(service: "telegram", country: "PK")
wait_for_sms(order_id: "abc123")

Number not receiving? Swap it

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

Rent a number for a month

rentals_available(tier: "full_access")
→ countries holding local SIM stock, each with its own duration and price list

create_rental(tier: "full_access", country: "FR", duration_hours: 720)
→ {rental_id: "rnt_1", phone_number: "+33...", expires_in_days: 30}

Stock is per country and per tier, so discover first and rent second. rentals_available(tier: "platform") covers a different, service-locked catalogue.

Pair a number with a matching-country proxy

list_proxy_catalog()
buy_proxy(pool_type: "residential", gb: 1, country_code: "GB")
generate_proxy_endpoint(proxy_id: "px_1", country_code: "GB", protocol: "socks5")

---

Questions

What is account verification infrastructure?

Account verification infrastructure is the stack that gets a real account through a signup flow that demands a phone number. It has five layers, and a gap in any one of them fails the whole chain:

1. Numbers. A carrier-issued mobile line, because the line type gets checked.
2. SMS. The verification code, delivered to that number and readable by software rather than by a human holding a handset.
3. Proxy. An IP in the same country as the number, so the two agree.
4. Browser. A clean environment to drive the signup itself.
5. Automation. An API or an agent that runs the chain end to end, unattended.

Most providers sell the first two layers and leave you to source the rest, which is exactly where the number, the IP and the browser stop telling the same story. VirtualSMS provides the infrastructure behind all five.

VirtualSMS is an account verification platform for individuals, developers, and AI agents. It combines one-time SMS verification, dedicated number rentals, matching-country proxies, and private cloud browser sessions behind one API, one MCP server, and one prepaid balance.

What is an MCP server for SMS verification?

MCP (Model Context Protocol) is an open standard that lets an AI client call external tools. An MCP server for SMS verification exposes phone-number and verification-code operations as tools an agent can call directly, so the agent buys the number, waits for the code and reads it back without any glue code from you. This repo is that server for VirtualSMS: 40 tools covering verification, rentals and proxies. If you are not driving an agent at all, the same operations are available as a plain REST verification API.

When should I use this?

• Your AI agent needs to sign in to or register an account that demands a phone number.
• You are testing an OTP or signup flow and want fresh numbers on demand instead of a drawer of test SIMs.
• You need a verification code retrieved automatically, in CI or in an unattended job.
• You need a number and a matching-country IP that agree with each other.
• You are driving signup automation in a browser and would rather the number, the IP and the browser came from one place than three.
• You need a temporary phone number for one code, or a dedicated one you keep for up to 30 days.
• You want per-code pricing from $0.05 with no subscription and no monthly number rental.

When should I NOT use this?

Honest answers, so you do not waste an afternoon:

• You need to send SMS. This platform receives; it does not send. Use a messaging provider such as Twilio.
• You need a permanent number for your business. Verification numbers are temporary by design, and rentals run in days, not years. Buy a real line from a carrier.
• You need codes on a number you already own. There is no port-in. The numbers come from our inventory.
• You are running A2P marketing campaigns. Wrong tool entirely.
• You are trying to evade a platform’s terms of service. Whether your use complies with the terms of the service you verify against is your responsibility, not ours.

Can Claude or Cursor receive SMS verification codes?

Yes, through this server. Claude Code, Claude Desktop, Cursor, Windsurf, Cline, Zed, Continue.dev, Codex, OpenClaw and Hermes are all MCP clients, and each one is a config paste away (see Client setup). Once installed, “buy a Telegram number and wait for the code” is a request the agent can carry out end to end. ChatGPT can reach it too, through Developer Mode custom connectors (see Does this work with ChatGPT?), or through the REST API if you would rather not enable Developer Mode.

How do AI agents receive OTP codes automatically?

Two tool calls. create_order buys a number for a given service and country and returns an order_id. wait_for_sms then blocks on that order_id and returns the moment the code arrives, pushed over WebSocket, typically in 2 to 15 seconds. The agent never polls, never sleeps in a loop, and never needs a human to read a phone. If you would rather drive your own loop, get_sms polls a single order instead.

How is this different from Twilio?

Twilio is a full communications platform: send and receive SMS and voice, long-lived numbers, A2P campaigns, the lot. VirtualSMS does one job, which is receiving verification codes on demand. The practical differences:

• Line type. Twilio numbers are VoIP. Many services reject VoIP numbers at signup. VirtualSMS numbers are real physical SIM cards on carrier networks, so they resolve as mobile.
• Pricing shape. Twilio bills you for a number every month whether you use it or not. VirtualSMS bills per code from $0.05, with no subscription.
• Direction. Twilio sends and receives. This receives.

If you need to send messages, use Twilio. If you need to receive a verification code, this is purpose-built for it.

Why real physical SIM cards instead of VoIP?

Verification systems check the line type of the number you give them. VoIP numbers are cheap and disposable at scale, so they correlate with fraud, and a large share of services reject them outright at signup. Real physical SIM cards sit on carrier networks and resolve as mobile, which is exactly what those checks are looking for: a non-VoIP number that behaves like a real handset.

You do not have to take that on faith. check_number runs a carrier and line-type lookup on any E.164 number, needs no API key, and will tell you whether a number reads as mobile, landline or VoIP.

---

Alternatives and comparisons

Developers searching for textverified mcp, sms-activate mcp, 5sim mcp, daisysms mcp or smspool mcp are usually asking one question: which SMS verification provider can an AI agent drive natively? This section answers that without a scoreboard.

VirtualSMS publishes this MCP server, so any MCP client calls it directly with no wrapper code: 40 tools, 2500+ services, 145+ countries, from $0.05 per code, on real physical SIM cards, plus number rentals and matching-country proxies from the same balance.

SMS-Activate shut down in December 2025. If your integration pointed there, it is gone, and the migration is a new API key and a new base URL rather than a rewrite: the shape of the job, buy a number then read the code, is the same here.

TextVerified, 5SIM, DaisySMS and SMSPool are all active SMS verification providers, each with its own API, pricing, coverage and terms. Check their current documentation for what they offer today.

We deliberately do not publish a comparison table of competitors’ prices, service counts or coverage. Those numbers move week to week, we have no privileged view into anyone else’s inventory, and a stale table dressed up as research is worse than no table at all. The VirtualSMS numbers above are ours and we stand behind them. Compare them against whatever you are using now.

---

How it works

WebSocket and polling

wait_for_sms uses a two-tier delivery system:

1. WebSocket, instant. Connects to wss://virtualsms.io/ws/orders?order_id=xxx&api_key=your_key. When the SMS arrives the server pushes it in real time. Typical delivery: 2 to 15 seconds.
2. Polling fallback. If the WebSocket fails to connect or drops, the tool falls back to polling every 5 seconds for the remaining timeout.

The delivery_method field in the response tells you which path was used: websocket, polling, or instant when the code had already landed before you called.

This server pushes over a held-open WebSocket; it never calls you back. If you would rather VirtualSMS POST events to a URL you own, the platform runs a separate webhook subscription system, configured from the dashboard and driven by the REST API rather than by this MCP server.

Architecture

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

Crash recovery

If your session is interrupted mid-verification:

1. Restart the MCP server.
2. List active orders: list_orders(status: "pending")
3. Check for codes: get_sms(order_id: "abc123")
4. Cancel if not needed: cancel_order(order_id: "abc123")

wait_for_sms always returns order_id, even on timeout, so you can recover.

---

Hosted endpoint and status

• Hosted MCP endpoint: https://mcp.virtualsms.io/mcp. TLS-only StreamableHTTP, fronted by Cloudflare.
• Platform status and uptime: virtualsms.io/status, polled live: website and dashboard, SMS gateway, REST API, Telegram bot and database. The hosted MCP endpoint runs as a separate service and is not yet a row on that page.
• Target SLA: 99.9% on the hosted MCP path. A target we hold ourselves to rather than a contractual guarantee, and one the status page above does not yet measure.
• Coverage: 145+ countries online, 2500+ services indexed.
• Data retention: SMS message bodies are retained 7 days, then permanently deleted. Order metadata (phone number, service, country, timestamps) is retained for the lifetime of your account. See SECURITY.md for full details.
• Vulnerability disclosure: email [email protected] or open a private security advisory.

👉 Sign up at VirtualSMS.io

---

Examples

Three runnable examples are checked into this repo. Each is node run.mjs away once VIRTUALSMS_API_KEY is set.

• examples/01-quick-balance-check/: 5-second hosted MCP smoke test (get_balance).
• examples/02-buy-sms-and-wait-for-code/: full verification flow, find_cheapest → create_order → wait_for_sms → cancel-on-timeout. The canonical pattern for AI agents.
• examples/03-claude-desktop-config/: drop-in Claude Desktop config plus a transcript of “ask Claude what’s my balance” over StreamableHTTP.

SDKs and tools

The same platform, from whatever you already write in:

---

Build and contribute

git clone https://github.com/virtualsms-io/mcp-server.git
cd mcp-server
npm install
npm run build      # tsc
npm test           # vitest
npx tsc --noEmit   # typecheck only

Two transports share one tool table: src/index.ts (stdio) and src/http-server.ts (StreamableHTTP). Tool definitions and handlers live in src/tools.ts. If you add a tool, wire it into both transports. src/__tests__/transport-parity.test.ts fails the build if you forget, and src/__tests__/docs-tool-names.test.ts fails if the docs name a tool that does not exist.

Issues and pull requests: github.com/virtualsms-io/mcp-server.

Release notes for v1.0.0 to v1.3.1 are in CHANGELOG.md.

Security

API keys are passed via the x-api-key header (hosted) or the VIRTUALSMS_API_KEY environment variable (local stdio), and are rotatable from your account at virtualsms.io. Full policy, retention detail and disclosure process: SECURITY.md.

Report vulnerabilities to [email protected].

License

MIT. See LICENSE.

Built by VirtualSMS.io. Account verification for developers and AI agents, on real physical SIM cards: 2500+ services · 145+ countries · from $0.05 per code.