io.github.virtualsms-io/sms

Purchase proxy traffic (GB) for a selected pool type. Returns proxy credentials and remaining balance. country_code here is only a soft preference for provisioning. For actual per-connection targeting (country/state/city/zip/asn) or a ready-to-use connection string, use virtualsms_generate_proxy_endpoint after buying. To persist a default targeting on the sub-user, use virtualsms_set_proxy_targeting.

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.

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

Cancel a rental for a full refund. Only eligible within 20 minutes of purchase AND before any SMS has been received. Works for either tier. Past that window a rental runs to its natural expiry.

Public carrier + line-type lookup for an arbitrary E.164 phone number (mobile/landline/VoIP, spam risk). No API key required.

Purchase a virtual phone number for SMS verification. Returns order_id and phone_number. Codes typically arrive within ~10-60 seconds after purchase. Use get_sms to poll for the verification code, or use wait_for_sms to block until it arrives.

Rent a phone number for an extended period (as opposed to a one-off number via create_order). Two tiers: "full_access" = local SIM inventory, works across ANY service on that number. "platform" = sourced via our global supplier network, locked to ONE chosen service, durations 1/3/7 days only. Both tiers carry the same refund terms: a full refund within 20 minutes of purchase and before the first SMS arrives. Check rentals_available and rentals_price/rentals_pricing first to confirm country/service/duration and cost.

Extend an active rental by an additional duration. Charges your balance at the current catalog price for that duration.

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.

Build ready-to-use proxy connection string(s) for an owned proxy: country/state/city/zip/asn targeting, rotating or sticky session, HTTP or SOCKS5, in host:port:user:pass / user:pass@host:port / curl format. Nothing is purchased or changed server-side. This only composes a connection string from the proxy's existing credentials (same convention as the VirtualSMS dashboard's endpoint generator). Sub-country targeting (state/city/zip/asn) bills the proxy's own GB at 2x on non-premium pools, free on residential_premium.

Check your VirtualSMS account balance in USD. Requires VIRTUALSMS_API_KEY to be set.

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 get_sms returns.

Check the price and availability for a specific service + country combination. Always check price before buying to confirm availability.

Full account profile: email, Telegram link status, current balance, lifetime spend, total orders, active API keys, and account creation date.

Get cached GB used/remaining and request count for one proxy. Cheap, no upstream call. Reads a cached value refreshed every ~5 minutes.

Get a per-day traffic (GB) and request-count series for one proxy over the last 7 or 30 days.

Get the full details of a specific rental by ID, including tier, phone number, country, service lock, status, expiry, and any received SMS. Use list_rentals first if you do not have the rental_id.

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.

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.

Transaction history for the account with optional filters for type, date range, and pagination. Types: "deposit", "purchase", "refund", "admin_credit".

Get all available countries for SMS verification. Use this to discover valid country codes before buying a number.

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 get_sms to retrieve codes.

List all proxies on your account with remaining GB and login credentials. Returns proxy_id values for use with get_proxy_usage, rotate_proxy, set_proxy_targeting, and generate_proxy_endpoint.

List available proxy pool types, countries, and price-per-GB. Use this before buying proxy traffic.

List available cities, states, ASNs, or ZIP codes for a pool type + country. Use this to discover valid location_code values before calling virtualsms_generate_proxy_endpoint or virtualsms_set_proxy_targeting with sub-country targeting. Public endpoint, no purchase required. Not available for residential_premium (only residential, mobile, datacenter).

List your rentals across both tiers, optionally filtered by status. Returns rental_id, tier, country, phone number, status, and expiry for each. Use get_rental for full detail on one.

Get all available SMS verification services (Telegram, WhatsApp, Google, etc.). Use this to discover valid service codes before buying a number.

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.

List countries with rental stock, available counts, and pricing. tier=full_access (default) shows local-SIM inventory; tier=platform shows countries available via our global supplier network (with per-country service counts and popular services). Use this before creating a rental.

Get the catalog-driven retail price for a (service, country, duration) platform-tier rental combo.

List all active rental pricing tiers (Full Access tier: local SIM inventory, durations and prices). This is a raw catalog dump and may list rows that are not purchasable today, so confirm against rentals_available (authoritative per country) before creating a rental. Use rentals_price for platform-tier (per-country, per-service) pricing instead.

List services available for platform-tier rental in a given country, with physical stock counts and retail price. Platform-tier rentals are locked to ONE chosen service per number. Use this to pick a valid service code before creating one.

Ask the provider to resend the SMS to the SAME phone number on an existing order (order must be in waiting/created status). Not all order types support this. Some providers only support swap_number instead, which returns a NEW number.

Request a fresh IP for an existing proxy. Useful when an endpoint flags the current exit IP.

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.

Persist a default geo-targeting (country, and optionally cities/ASNs) on an existing proxy sub-user. Country-only is free. Adding cities or ASNs bills the GB on your OWN allocation at 2x (not on residential_premium, where refined targeting is included free). This changes the STORED default. For a one-off connection string with any targeting (including state/zip), use virtualsms_generate_proxy_endpoint instead.

Beta, invite-only. Start a country-matched cloud browser you drive yourself: returns a viewer_url, an authenticated live-viewer link you open to watch and drive the session (manual takeover), plus optional order phone number and timeline. Agent-driven navigation is the separate opt-in session tools. Pair with create_order for OTP + browser in one agent flow.

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

Make one request through a proxy and report the exit IP, country, city, ISP, and latency. Proves the proxy works and which country it exits from. Consumes a small amount of the proxy's GB allocation. Rate-limited to about once per 20 seconds per proxy.

Wait (block) until the SMS arrives on an existing order_id, or until timeout. Codes typically arrive within ~10-60 seconds. This call BLOCKS for up to timeout_seconds (default 60, max 600) before returning. 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.