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:

You want to	Ask your agent	Tools it uses
Verify a WhatsApp account from Claude Code	"Get me a WhatsApp code on a UK number"	create_order → wait_for_sms
Create a Telegram account from Cursor	"Buy a Telegram number in the cheapest country and wait for the code"	find_cheapest → create_order → wait_for_sms
Retrieve verification codes automatically	"Wait for the code and paste it into the form"	wait_for_sms
Test OTP flows during QA	"Run the signup flow ten times and report which codes landed"	create_order → wait_for_sms → cancel_order
Provision temporary numbers during CI	"Give the test suite a fresh number, then release it"	create_order → get_sms → cancel_order
Keep a number for a week	"Rent me a British number for 7 days"	rentals_available → create_rental
Make the number and the IP agree	"Buy a UK proxy to match my UK number"	list_proxy_catalog → buy_proxy → generate_proxy_endpoint
Screen a number before you trust it	"Is this number VoIP?"	check_number (no API key required)
Recover a number that went quiet	"That number never got the code, swap it"	swap_number

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/.

Claude Code (CLI)

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

Cursor

Edit ~/.cursor/mcp.json:

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

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json:

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

OpenClaw

Edit ~/.openclaw/mcp.json:

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

Codex (OpenAI Codex CLI)

Edit ~/.codex/config.toml:

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

Hermes

Edit your Hermes MCP config:

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

Cline (VS Code)

Open the Cline MCP settings panel and add:

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

Zed

Edit ~/.config/zed/settings.json:

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

Continue.dev

Edit ~/.continue/config.yaml:

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

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

Variable	Required	Default	Description
VIRTUALSMS_API_KEY	Yes, for account tools	none	Your VirtualSMS API key. Keys carry a vsms_ prefix
VIRTUALSMS_BASE_URL	No	https://virtualsms.io	API base URL
VIRTUALSMS_ENABLE_SESSIONS	No	off	Serves 3 additional session-drive tools when set to 1, true or yes. Off by default
VIRTUALSMS_ENABLE_RELEASE	No	off	Serves the early-release rental tool when set to 1, true or yes. Off by default while its refund terms are being settled

---

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.

The core SMS verification surface: discover a service, price it, buy a number, get the code.

Tool	Auth	Description
list_services	Yes	All available verification services. Optional search filter
list_countries	Yes	All available countries. Optional service filter
get_price	No	Price and availability for a service plus country pair
find_cheapest	No	Cheapest countries for a service, sorted by price, with stock levels
search_services	Yes	Natural-language service lookup. "telega" finds Telegram
get_balance	Yes	Account balance in USD
get_profile	Yes	Email, Telegram link, balance, lifetime spend, total orders, active API keys
get_stats	Yes	Orders, success rate, spend, and status/service/country breakdown
get_transactions	Yes	Transaction history with type, date range, and pagination filters
create_order	Yes	Buy a number for a service plus country. Returns order_id and phone_number
get_sms	Yes	Poll an order for the code. Use for batch and cron jobs
wait_for_sms	Yes	Block until the SMS lands on an existing order_id, or until timeout
get_order	Yes	Full order detail plus every received message
list_orders	Yes	Your active orders. Essential for crash recovery
order_history	Yes	Past orders with status, service, country, and date filters
cancel_order	Yes	Cancel and refund, if no SMS arrived. 120s cooldown after purchase
cancel_all_orders	Yes	Bulk-cancel every active order
swap_number	Yes	Swap for a new number, same service and country, no extra charge. 120s cooldown

get_sms vs wait_for_sms: wait_for_sms is the recommended default for interactive agent workflows. It blocks and returns the moment the SMS arrives over WebSocket. Use get_sms for batch jobs, cron-driven polling, or when you already manage your own polling loop.

wait_for_sms takes an order_id, not a service and country. Call create_order first, then pass the returned order_id. That is the two-step buy-and-wait flow.

Keep a number by the day instead of buying a single verification. Two tiers:

• Full Access: local SIM inventory, for a whole number that works across any service. Every country in stock today lists 1, 7 and 30 days, at prices that vary per country. Durations and prices are not hardcoded here on purpose: call rentals_available for the live list per country and treat that as authoritative.
• Platform: sourced via our global supplier network, locked to one chosen service, durations of 1, 3 or 7 days. Call rentals_price for the exact retail price of a (service, country, duration) combo.

Stock, durations and pricing all differ per tier and per country, so call rentals_available before committing to either. An active rental can be extended with extend_rental at the current catalog price, in the same durations its tier allows.

Both tiers carry the same refund terms: cancel for a full refund within 20 minutes of purchase and before the first SMS arrives. Platform cancels are additionally subject to a 2 minute minimum hold, so a cancel inside the first 2 minutes is rejected and has to be retried.

Tool	Auth	Description
rentals_pricing	Yes	Full Access pricing tiers: durations and prices
rentals_available	Yes	Countries with rental stock, counts, and pricing, per tier
rentals_services	Yes	Services available for Platform-tier rental in a country, with stock and price
rentals_price	Yes	Retail price for a service, country, and duration combination
create_rental	Yes	Rent a number. Check availability and price first
list_rentals	Yes	Your rentals across both tiers, filterable by status
get_rental	Yes	Full detail for one rental: tier, number, service lock, status, expiry, SMS
extend_rental	Yes	Extend an active rental. Charges the current catalog price
cancel_rental	Yes	Full refund, within 20 minutes of purchase and before any SMS

Matching-country proxies, so the number and the IP agree. Three pools: residential, mobile and datacenter. Buy traffic by the GB, then generate a connection string.

Tool	Auth	Description
list_proxy_catalog	Yes	Pool types, countries, and price per GB. Start here
list_proxy_locations	No	Cities, states, ASNs, or ZIPs for a pool type plus country. No purchase required
buy_proxy	Yes	Purchase proxy traffic in GB. Returns credentials and remaining balance
list_proxies	Yes	Your proxies with remaining GB and credentials. Returns proxy_id values
generate_proxy_endpoint	Yes	Build a ready-to-use connection string: country, state, city, ZIP or ASN targeting, rotating or sticky, HTTP or SOCKS5
rotate_proxy	Yes	Request a fresh exit IP for an existing proxy
test_proxy	Yes	Prove a proxy works. Reports exit IP, country, city, ISP, and latency
get_proxy_usage	Yes	Cached GB used and remaining, plus request count, for one proxy
get_proxy_usage_history	Yes	Per-day traffic and request series over the last 7 or 30 days
set_proxy_targeting	Yes	Persist a default geo-targeting on a proxy sub-user

Tool	Auth	Description
retry_order	Yes	Ask for the SMS to be resent to the same number. Not all order types support it
check_number	No	Carrier and line-type lookup for any E.164 number: mobile, landline or VoIP, plus spam risk
start_manual_registration_session	Yes	Beta, invite-only. Start a country-matched cloud browser you drive yourself in a live viewer. Agent-driven navigation is a separate opt-in (the session tools). Join https://t.me/VirtualSMS_io for beta access

Beta, invite-only. The browser stack is early. It works, but the shape of these tools can still change and there is no stability guarantee yet. Join https://t.me/VirtualSMS_io for beta access and updates.

Served only when VIRTUALSMS_ENABLE_SESSIONS is set to 1, true or yes. Not exposed on the default surface.

Tool	Description
navigate_session	Navigate an active browser session to a URL
session_viewer	Live viewer URL and current status for an active session
stop_session	Stop an active browser session and release it

---

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