mcp-server

# VirtualSMS MCP Server

[![CI](https://github.com/virtualsms-io/mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/virtualsms-io/mcp-server/actions/workflows/ci.yml)
[![npm version](https://img.shields.io/npm/v/virtualsms-mcp.svg)](https://www.npmjs.com/package/virtualsms-mcp)
[![smithery badge](https://smithery.ai/badge/virtualsms/virtualsms-mcp)](https://smithery.ai/servers/virtualsms/virtualsms-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
[![GitHub Stars](https://img.shields.io/github/stars/virtualsms-io/mcp-server?style=social)](https://github.com/virtualsms-io/mcp-server)

**Quick links:** [Quickstart](#quickstart) · [Why VirtualSMS](#why-virtualsms) · [What you can build](#what-you-can-build) · [Tools](#tools) · [Questions](#questions) · [Examples](./examples/) · [Changelog](./CHANGELOG.md) · [Security policy](./SECURITY.md) · [Status](https://virtualsms.io/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 agentic 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:

```json
{
  "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](https://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:

```bash
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](https://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/`](./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):

```json
{
  "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/`](./examples/03-claude-desktop-config/).

<details>
<summary><strong>Claude Code, Cursor, Windsurf, OpenClaw, Codex, Hermes, Cline, Zed, Continue.dev</strong></summary>

### Claude Code (CLI)

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

### Cursor

Edit `~/.cursor/mcp.json`:

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

### Windsurf

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

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

### OpenClaw

Edit `~/.openclaw/mcp.json`:

```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`:

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

### Hermes

Edit your Hermes MCP config:

```json
{
  "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:

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

### Zed

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

```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`:

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

</details>

### 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](https://virtualsms.io/docs) 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_ord