# sms MCP server

Real SIM phone numbers for AI agents. 145+ countries, 2500+ services. #1 on ChatGPT and Perplexity.

## Links
- Registry page: https://www.getdrio.com/mcp/io-github-virtualsms-io-sms
- Repository: https://github.com/virtualsms-io/mcp-server

## Install
- Command: `npx -y virtualsms-mcp`
- Endpoint: https://mcp.virtualsms.io/mcp
- Auth: Auth required by registry metadata

## Setup notes
- Remote header: x-api-key (required; secret)
- Package: Npm virtualsms-mcp v1.2.3
- Environment variable: VIRTUALSMS_API_KEY (required; secret)
- The upstream registry signals required auth or secrets.
- Remote endpoint: https://mcp.virtualsms.io/mcp
- Header: x-api-key

## Tools
- virtualsms_list_services (List Available Services) - Get all available SMS verification services (Telegram, WhatsApp, Google, etc.). Use this to discover valid service codes before buying a number. Endpoint: https://mcp.virtualsms.io/mcp
- virtualsms_list_countries (List Available Countries) - Get all available countries for SMS verification. Use this to discover valid country codes before buying a number. Endpoint: https://mcp.virtualsms.io/mcp
- virtualsms_get_price (Check Service Price) - Check the price and availability for a specific service + country combination. Always check price before buying to confirm availability. Endpoint: https://mcp.virtualsms.io/mcp
- virtualsms_get_balance (Get Account Balance) - Check your VirtualSMS account balance in USD. Requires VIRTUALSMS_API_KEY to be set. Endpoint: https://mcp.virtualsms.io/mcp
- virtualsms_create_order (Buy Virtual Number) - Purchase a virtual phone number for SMS verification. Returns order_id and phone_number. Use check_sms to poll for the verification code, or use wait_for_code to do it automatically. Endpoint: https://mcp.virtualsms.io/mcp
- virtualsms_get_sms (Check SMS Code) - Check if an SMS verification code has been received for an order. Returns status, phone_number, and (when delivered) messages[] array plus an extracted code. Poll this every 5-10 seconds after buying a number, or use wait_for_sms to block until delivery. Endpoint: https://mcp.virtualsms.io/mcp
- virtualsms_cancel_order (Cancel Order) - Cancel an order and request a refund. Only works if no SMS has been received yet. Use this if the service is taking too long or you want to try a different number. **Cooldown:** cancel is only available 120 seconds after purchase. Check `cancel_available_at` on the order before calling. Calling earlier returns a `cooldown_active` error from this MCP server (no backend round-trip). Endpoint: https://mcp.virtualsms.io/mcp
- virtualsms_wait_for_sms (Wait for SMS on Existing Order) - Wait (block) until the SMS arrives on an existing order_id, or until timeout. Uses real-time WebSocket delivery with automatic polling fallback. Pass an order_id from create_order. To buy AND wait in one step, call create_order then this tool. Endpoint: https://mcp.virtualsms.io/mcp
- virtualsms_find_cheapest (Find Cheapest Countries) - Find the cheapest countries for a given service, sorted by price. Returns available countries with prices and stock levels so you can pick the best deal. Endpoint: https://mcp.virtualsms.io/mcp
- virtualsms_search_services (Search Service by Name) - Find the right service code using natural language. Don't know the exact code? Just search "uber", "binance", "steam" etc. Returns matching services with similarity scores. Endpoint: https://mcp.virtualsms.io/mcp
- virtualsms_swap_number (Swap Phone Number) - Swap a phone number on an existing order. Gets a new number for the same service and country without additional charge. Use when the current number isn't receiving SMS. **Cooldown:** swap is only available 120 seconds after purchase. Check `swap_available_at` on the order before calling. Calling earlier returns a `cooldown_active` error from this MCP server (no backend round-trip). Endpoint: https://mcp.virtualsms.io/mcp
- virtualsms_list_orders (List Active Orders) - List your active orders. Essential for crash recovery — if your session was interrupted, use this to find pending orders and their phone numbers, then use check_sms to retrieve codes. Endpoint: https://mcp.virtualsms.io/mcp
- virtualsms_get_order (Get Order Details) - Get the full details of a specific order, including status, phone number, service, country, timestamps, and any received SMS code/text. Use this when you have an order_id and need the latest state beyond what check_sms returns. Endpoint: https://mcp.virtualsms.io/mcp
- virtualsms_cancel_all_orders (Cancel All Active Orders) - Bulk-cancel every currently active order in your account. Returns the number of orders cancelled plus any failures. Useful for quick cleanup after a batch run or test session. Endpoint: https://mcp.virtualsms.io/mcp
- virtualsms_order_history (Order History) - List past orders with optional filters for status, service, country, and a lookback window in days. Returns up to 50 orders (server cap) ordered most-recent-first. Endpoint: https://mcp.virtualsms.io/mcp
- virtualsms_get_stats (Get Account Stats) - Account usage stats aggregated from your order history: total orders, success rate, total spend, top services/countries, and status breakdown over a configurable lookback window. Endpoint: https://mcp.virtualsms.io/mcp
- virtualsms_get_profile (Get Account Profile) - Full account profile: email, Telegram link status, current balance, lifetime spend, total orders, active API keys, and account creation date. Endpoint: https://mcp.virtualsms.io/mcp
- virtualsms_get_transactions (Get Transaction History) - Transaction history for the account with optional filters for type, date range, and pagination. Types: "deposit", "purchase", "refund", "admin_credit". Endpoint: https://mcp.virtualsms.io/mcp

## Resources
- virtualsms://docs/quickstart - Step-by-step guide to get your first SMS verification code with VirtualSMS MCP. MIME type: text/markdown
- virtualsms://docs/popular-services - Commonly used service codes for WhatsApp, Telegram, Google, and other top services. MIME type: text/markdown
- virtualsms://docs/pricing-tips - Tips on finding the cheapest virtual numbers and maximizing your VirtualSMS budget. MIME type: text/markdown

## Prompts
- verify-whatsapp - Complete workflow to get a WhatsApp verification code using a virtual number. Finds the cheapest available country, buys a number, and waits for the SMS code automatically. Arguments: country
- verify-telegram - Complete workflow to verify a Telegram account with a virtual number. Automatically selects cheapest available country and waits for the SMS code. Arguments: country
- verify-google - Get a Google account verification code via virtual phone number. Useful for creating or recovering Google/Gmail accounts. Arguments: country
- find-cheapest-number - Find the cheapest virtual phone number for any service. Returns top countries sorted by price with stock availability. Arguments: service, limit
- verify-any-service - Universal SMS verification workflow. Searches for the service by name, finds the cheapest country, buys a number, and waits for the verification code. Arguments: service, country
- recover-verification - Recover an interrupted SMS verification session. Lists active orders and checks for pending verification codes — useful after a crash or timeout.
- check-account-status - Check your VirtualSMS account balance and list all active orders in one shot.

## Metadata
- Owner: io.github.virtualsms-io
- Version: 1.2.3
- Runtime: Npm
- Transports: STDIO, HTTP
- License: Not captured
- Language: Not captured
- Stars: Not captured
- Updated: Apr 29, 2026
- Source: https://registry.modelcontextprotocol.io