# io.github.virtualsms-io/sms (npm · virtualsms-mcp)

Real physical SIMs for AI agents: SMS verification and rentals. 145+ countries, 2500+ services.

- Trust score: 68/100 (medium)
- Change this week: +15
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-08-03

## Components

- remote · `mcp.virtualsms.io`: 36/100, [markdown](https://verifymcp.io/servers/virtualsms-io-sms/mcp.md), [page](https://verifymcp.io/servers/virtualsms-io-sms/mcp)
- npm · `virtualsms-mcp`: 68/100 (this document), [markdown](https://verifymcp.io/servers/virtualsms-io-sms/virtualsms-mcp.md), [page](https://verifymcp.io/servers/virtualsms-io-sms/virtualsms-mcp)

## Channel facts

- Registry: `npm`
- Package: `virtualsms-mcp`
- Version: `1.3.1`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-08-03.

- **Supply Chain Security**: 87/100
  - No malware found by supply-chain analysis.
  - Only part of the dependency tree could be resolved (109 of 110), so this covers what we could see, not the whole tree.
  - No install/post-install scripts declared.
  - Only part of the dependency tree could be resolved (109 of 110), so this covers what we could see, not the whole tree.
- **Provenance & Transparency**: 45/100
  - Source repository is publicly reachable at the declared URL.
  - Provenance check failed: no build-provenance attestation is published.
  - Clear OSI-approved license (MIT).
  - Actively maintained (last published 15 days ago).
  - Disclosure check failed: no security disclosure policy was found in the source repository.
- **Schema Quality & AI Usability**: 88/100
  - 100% of prompts and resources have a non-trivial description (not blank, and not just the item's name).
  - AI-judged instruction clarity (excellent).
  - Tool/resource definitions use about 4128 tokens (~96/item across 43 items; 40 tools + 3 resources), lean.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 0/100
  - Stability not yet verified: not enough scan history yet (needs a 30-day window).
- **Tool Coverage**: 100/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 100% of tool parameters carry a description.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.

**Unverified: 1 category.** A category scored 0 because we could not verify it: a data source with nothing on this package, evidence we could not reach, or a check we could not run. We only credit what we can confirm.

## Install

### Claude

```bash
claude mcp add virtualsms-io-sms -- npx -y virtualsms-mcp
```

### Codex

```bash
codex mcp add virtualsms-io-sms -- npx -y virtualsms-mcp
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "virtualsms-io-sms": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "virtualsms-mcp"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add virtualsms-io-sms --command npx --arg -y --arg virtualsms-mcp
```

### Hermes

```yaml
mcp_servers:
  virtualsms-io-sms:
    command: "npx"
    args: ["-y", "virtualsms-mcp"]
```

### Other

```json
{
  "mcpServers": {
    "virtualsms-io-sms": {
      "command": "npx",
      "args": [
        "-y",
        "virtualsms-mcp"
      ]
    }
  }
}
```

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-08-02 (score 68, +42)

- [security regression] Provenance: unverified → fail
- [security improvement] Install scripts: unverified → pass
- [security improvement] Known CVEs: unverified → partial
- [security improvement] Malware scan: unverified → pass
- [security] Stability: Stability not yet verified: not enough scan history yet (needs a 30-day window).
- [functional improvement] MCP protocol: unverified → pass
- [functional improvement] Schema quality: unverified → excellent
- [functional improvement] License: unverified → pass
- [functional improvement] Dependency health: unverified → partial
- [functional improvement] Maintenance: unverified → pass
- [functional] Licence: MIT

### 2026-07-31 (score 26, +2)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-30 (score 24, −29)

- [functional regression] Tool coverage: 100 → unverified
- [functional regression] Schema quality: 100 → unverified

### 2026-07-27 (score 53)

First indexed and scored.

## MCP tools (40)

### `virtualsms_list_proxy_catalog` (~32 tokens)

List Proxy Catalog

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

### `virtualsms_list_proxies` (~48 tokens)

List My Proxies

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.

### `virtualsms_buy_proxy` (~165 tokens)

Buy Proxy GB

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.

Input parameters:

- `country_code` (string): Optional ISO-2 country preference (e.g. us, gb)
- `gb` (number, required): Amount of traffic to add in GB
- `idempotency_key` (string): Optional key for safe retries without double charges
- `pool_type` (string, required): Pool type: residential, residential_premium, mobile, datacenter

### `virtualsms_rotate_proxy` (~63 tokens)

Rotate Proxy IP

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

Input parameters:

- `port` (number): Optional proxy port. Defaults to rotating HTTP port.
- `proxy_id` (string, required): Proxy ID returned by list_proxies or buy_proxy

### `virtualsms_get_proxy_usage` (~58 tokens)

Get Proxy Usage

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

Input parameters:

- `proxy_id` (string, required): Proxy ID returned by list_proxies or buy_proxy

### `virtualsms_get_proxy_usage_history` (~70 tokens)

Get Proxy Usage History

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

Input parameters:

- `proxy_id` (string, required): Proxy ID returned by list_proxies or buy_proxy
- `range` (string): History window (default: 7d)

### `virtualsms_set_proxy_targeting` (~179 tokens)

Set Proxy Default Targeting

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.

Input parameters:

- `asns` (array): Optional ASN numbers. Triggers 2x billing on non-premium pools
- `cities` (array): Optional city slugs. Triggers 2x billing on non-premium pools
- `country_code` (string, required): ISO-2 country code (required)
- `proxy_id` (string, required): Proxy ID returned by list_proxies or buy_proxy

### `virtualsms_test_proxy` (~140 tokens)

Test Proxy Connectivity

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.

Input parameters:

- `country` (string, required): ISO-2 country to test the exit IP through (e.g. "us", "gb")
- `protocol` (string): Protocol to test (default: http)
- `proxy_id` (string, required): Proxy ID returned by list_proxies or buy_proxy
- `session` (string): Connection session type (default: rotating)

### `virtualsms_list_proxy_locations` (~122 tokens)

List Proxy Locations

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

Input parameters:

- `country` (string, required): ISO-2 country code (e.g. "US", "DE")
- `kind` (string, required): Which location dimension to list
- `pool_type` (string, required): Pool type

### `virtualsms_generate_proxy_endpoint` (~310 tokens)

Generate Proxy Connection Endpoint

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.

Input parameters:

- `count` (number): How many endpoint strings to generate (default: 1)
- `country_code` (string, required): ISO-2 country to target (e.g. "us", "gb")
- `format` (string): Output string format (default: host:port:user:pass)
- `location_code` (string): Location value matching target_by. Required when target_by is not "country"
- `protocol` (string): Proxy protocol (default: HTTP)
- `proxy_id` (string, required): Proxy ID returned by list_proxies or buy_proxy
- `session` (string): rotating = new IP per connection (default). sticky = holds one IP per generated endpoint.
- `sticky_ttl_minutes` (number): How long a sticky session holds its IP, in minutes (default: 10)
- `target_by` (string): Refinement level (default: country)

### `virtualsms_start_manual_registration_session` (~196 tokens)

Start Manual Registration Session

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.

Input parameters:

- `country` (string): ISO-2 country for proxy match
- `device_mode` (string): Viewport profile
- `mode` (string): Session attach mode
- `order_id` (string): Activation order UUID to attach
- `prep_preset` (string): Prep preset
- `run_prep` (boolean): Run prep after start
- `service_name` (string): Service hint (telegram, whatsapp, …)
- `target_url` (string): URL for generic prep
- `with_proxy` (boolean): Attach matching VSMS proxy

### `virtualsms_list_services` (~51 tokens)

List Available Services

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

Input parameters:

- `search` (string): Filter services by name (optional)

### `virtualsms_list_countries` (~47 tokens)

List Available Countries

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

Input parameters:

- `service` (string): Filter countries available for a specific service (optional)

### `virtualsms_get_price` (~76 tokens)

Check Service Price

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

Input parameters:

- `country` (string, required): Country ISO code (e.g. "US", "GB", "RU")
- `service` (string, required): Service code (e.g. "telegram", "whatsapp", "google")

### `virtualsms_get_balance` (~45 tokens)

Get Account Balance

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

Input parameters:

- `currency` (string): Display balance in specific currency (default: USD)

### `virtualsms_create_order` (~103 tokens)

Buy Virtual Number

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.

Input parameters:

- `country` (string, required): Country ISO code (e.g. "US", "GB", "RU")
- `service` (string, required): Service code (e.g. "telegram", "whatsapp", "google")

### `virtualsms_get_sms` (~79 tokens)

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.

Input parameters:

- `order_id` (string, required): Order ID returned from create_order

### `virtualsms_cancel_order` (~103 tokens)

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

Input parameters:

- `order_id` (string, required): Order ID to cancel

### `virtualsms_wait_for_sms` (~140 tokens)

Wait for SMS on Existing Order

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.

Input parameters:

- `order_id` (string, required): Existing order ID returned from create_order
- `timeout_seconds` (number): How long to wait for SMS in seconds (default: 60, min: 5, max: 600)

### `virtualsms_find_cheapest` (~80 tokens)

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.

Input parameters:

- `limit` (number): Number of cheapest options to return (default: 5)
- `service` (string, required): Service code (e.g. "telegram", "whatsapp", "google")

### `virtualsms_search_services` (~71 tokens)

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.

Input parameters:

- `query` (string, required): Natural language search query (e.g. "uber", "whatsapp", "binance")

### `virtualsms_swap_number` (~111 tokens)

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

Input parameters:

- `order_id` (string, required): Order ID to swap. Must be in waiting/created status with no SMS received

### `virtualsms_list_orders` (~69 tokens)

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

Input parameters:

- `status` (string): Optional status filter: "pending", "sms_received", "cancelled", "completed"

### `virtualsms_get_order` (~72 tokens)

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

Input parameters:

- `order_id` (string, required): Order ID to retrieve full details for

### `virtualsms_cancel_all_orders` (~44 tokens)

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.

### `virtualsms_order_history` (~154 tokens)

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.

Input parameters:

- `country` (string): Optional country ISO code filter (e.g. "US", "GB")
- `limit` (number): Max orders to return (default: 20, server cap: 50)
- `service` (string): Optional service code filter (e.g. "telegram", "whatsapp")
- `since_days` (number): Only include orders from the last N days
- `status` (string): Optional status filter: "completed", "cancelled", "expired", "sms_received", "waiting"

### `virtualsms_get_stats` (~62 tokens)

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.

Input parameters:

- `since_days` (number): Window in days for activity stats (default: 30)

### `virtualsms_get_profile` (~38 tokens)

Get Account Profile

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

### `virtualsms_get_transactions` (~137 tokens)

Get Transaction History

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

Input parameters:

- `from` (string): Lower bound on created_at: RFC3339 or YYYY-MM-DD
- `limit` (number): Max transactions (1-200, default: 50)
- `offset` (number): Pagination offset (default: 0)
- `to` (string): Upper bound on created_at: RFC3339 or YYYY-MM-DD
- `type` (string): Filter by type: "deposit", "purchase", "refund", "admin_credit"

### `virtualsms_rentals_pricing` (~82 tokens)

List Rental Pricing Tiers

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.

### `virtualsms_rentals_available` (~122 tokens)

List Rental Country Availability

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.

Input parameters:

- `country` (string): Optional ISO-2 country filter
- `service` (string): Optional service filter (full_access tier only)
- `tier` (string): Which tier to list (default: full_access)
- `type` (string): Optional full_access sub-type filter

### `virtualsms_rentals_services` (~91 tokens)

List Platform-Tier Rental Services

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.

Input parameters:

- `country_code` (string, required): ISO-2 country code (e.g. "GR")
- `duration_hours` (number): Duration in hours (default: 24)

### `virtualsms_rentals_price` (~65 tokens)

Get Platform-Tier Rental Price

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

Input parameters:

- `country_code` (string, required): ISO-2 country code
- `duration_hours` (number, required): Duration in hours
- `service` (string, required): Service code

### `virtualsms_create_rental` (~211 tokens)

Create Rental

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.

Input parameters:

- `auto_renew` (boolean): full_access tier only. Auto-renew at expiry (default: false)
- `country` (string, required): ISO-2 country code
- `duration_hours` (number, required): Duration in hours (platform tier: 24, 72, or 168 only)
- `service` (string): Service code. Required for platform tier; optional for full_access
- `tier` (string, required): Rental tier

### `virtualsms_list_rentals` (~85 tokens)

List My Rentals

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.

Input parameters:

- `status` (string): Optional status filter: "active", "cancelled", "completed", "expired", or "all" (default: "active")

### `virtualsms_get_rental` (~69 tokens)

Get Rental Details

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.

Input parameters:

- `rental_id` (string, required): Rental ID to retrieve

### `virtualsms_extend_rental` (~58 tokens)

Extend Rental

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

Input parameters:

- `duration_hours` (number, required): Additional duration in hours to add
- `rental_id` (string, required): Rental ID to extend

### `virtualsms_cancel_rental` (~63 tokens)

Cancel Rental

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.

Input parameters:

- `rental_id` (string, required): Rental ID to cancel

### `virtualsms_retry_order` (~69 tokens)

Retry Order (Resend SMS)

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.

Input parameters:

- `order_id` (string, required): Order ID to retry

### `virtualsms_check_number` (~64 tokens)

Check Phone Number

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

Input parameters:

- `number` (string, required): Phone number in E.164 format (e.g. "+447911123456")

## Diagnostics

Captured diagnostic sections: Provenance, Dependencies. The full working is on the page: https://verifymcp.io/servers/virtualsms-io-sms/virtualsms-mcp#diagnostics

## Score history

- 2026-08-03: 68
- 2026-08-02: 68
- 2026-08-01: 26
- 2026-07-31: 26
- 2026-07-30: 24
- 2026-07-28: 53
- 2026-07-27: 53

## Links

- npm package: https://www.npmjs.com/package/virtualsms-mcp
- Socket report: https://socket.dev/npm/package/virtualsms-mcp
- Repository: https://github.com/virtualsms-io/mcp-server
- Changelog RSS feed: https://verifymcp.io/servers/virtualsms-io-sms/virtualsms-mcp/changelog.xml
- Changelog JSON feed: https://verifymcp.io/servers/virtualsms-io-sms/virtualsms-mcp/changelog.json
- HTML version of this page: https://verifymcp.io/servers/virtualsms-io-sms/virtualsms-mcp