Virtnumber MCP server
Commit Nov 7, 2026Allows AI agents to rent virtual phone numbers in 14 countries and read incoming SMS messages.
Also known as virtnumber/mcp, mcp
- Stars
- 0
- Tools
- 8
- Downloads, 30 days
- —
- Latest version
- 2.2.0
- Last commit
- Nov 7, 2026
- License
- MIT
What is Virtnumber MCP?
Virtnumber allows AI agents to rent virtual phone numbers in 14 countries and read incoming SMS messages. It exposes 8 tools, such as get_balance, get_pricing, list_my_numbers.
Summary generated from the project's README
About Virtnumber MCP server
Virtnumber provides a remote MCP server that allows AI agents to rent dedicated virtual phone numbers across 14 different countries. This service is designed for developers who need their agents to interact with SMS-based verification or communication systems. Users can connect via a streamable HTTP endpoint using OAuth 2.1 with PKCE for standard clients like Claude, Cursor, or VS Code. For headless agents, the server supports authentication through x-api-user and x-api-token headers.
The server includes specific tools for managing the entire lifecycle of a virtual number. Agents can use get_pricing to check costs, buy_number to rent a new line, and list_my_numbers to view active subscriptions. To handle incoming communications, the wait_for_sms tool allows an agent to pause for up to 55 seconds to capture a message, while list_messages retrieves received texts and detected codes. While all numbers receive SMS, only numbers in the US and Sweden support the send_sms tool for two-way communication.
What you can do with it
- 1Perform two-way SMS communicationInstruct an agent to send a text message using a dedicated number located in the United States or Sweden.
Written from the project's README. Every use case is checked against a quote from it.
How to install Virtnumber MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Virtnumber MCP in Claude Code
$ claude mcp add --transport http mcp https://www.virtnumber.com/mcpInstall Virtnumber MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"mcp": {
"url": "https://www.virtnumber.com/mcp"
}
}
}Install Virtnumber MCP in VS Code
.vscode/mcp.json
{
"servers": {
"mcp": {
"type": "http",
"url": "https://www.virtnumber.com/mcp"
}
}
}Install Virtnumber MCP in VS Code CLI
$ code --add-mcp '{"name":"mcp","type":"http","url":"https://www.virtnumber.com/mcp"}'Install Virtnumber MCP in Codex
$ codex mcp add mcp --url https://www.virtnumber.com/mcpInstall Virtnumber MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.mcp] url = "https://www.virtnumber.com/mcp"
Install Virtnumber MCP in Gemini CLI
$ gemini mcp add -s user --transport http mcp https://www.virtnumber.com/mcpInstall Virtnumber MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"mcp": {
"url": "https://www.virtnumber.com/mcp",
"type": "http"
}
}
}Virtnumber MCP tools 8
Detected from the READMEget_balanceget_pricinglist_my_numberslist_messageswait_for_smsbuy_numbersend_smsdelete_number
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablevirtnumber/mcp is public and reachablegithub.com/virtnumber/mcp ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-09github.com/virtnumber/mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model8 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeHTTPS endpoint answered 401 (sign-in required)Pass
README
View on GitHubVirtnumber MCP server
Rent phone numbers and read the SMS they receive, straight from your AI agent.
Virtnumber rents dedicated virtual phone numbers in 14 countries, one number to one customer. All numbers receive SMS. Two-way numbers in the US and Sweden can also send. This server gives AI agents the same account through the Model Context Protocol: your agent can check prices, rent a number, wait for the next SMS and read it.
- Endpoint:
https://www.virtnumber.com/mcp(Streamable HTTP, remote, nothing to install) - Sign-in: OAuth 2.1 with PKCE, discovered automatically. Dynamic client registration and client ID metadata documents are both supported.
- Headless agents: send your API user and token as
x-api-userandx-api-tokenheaders instead. - Listed in the official MCP Registry as
com.virtnumber/virtnumber.
Connect
Claude (web and desktop)
Settings, Connectors, Add custom connector, paste the server URL:
https://www.virtnumber.com/mcp
Claude Code
claude mcp add --transport http virtnumber https://www.virtnumber.com/mcp
Cursor
~/.cursor/mcp.json:
{
"mcpServers": {
"virtnumber": { "url": "https://www.virtnumber.com/mcp" }
}
}
VS Code
.vscode/mcp.json:
{
"servers": {
"virtnumber": { "type": "http", "url": "https://www.virtnumber.com/mcp" }
}
}
Clients that only run local (stdio) servers
Bridge the remote server with mcp-remote:
{
"mcpServers": {
"virtnumber": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://www.virtnumber.com/mcp"]
}
}
}
Headless agent (API key)
POST https://www.virtnumber.com/mcp
x-api-user: <your user id>
x-api-token: <your API token>
Create the API user and token under API in your Virtnumber account. Keep the token on your server: it can spend your balance.
Tools
| Tool | What it does |
|---|---|
get_balance |
Balance, this app's spending limit, permissions |
get_pricing |
Countries, plans and prices |
list_my_numbers |
Your rented numbers |
list_messages |
Read SMS on a number, with detected codes |
wait_for_sms |
Wait up to 55 s for the next SMS |
buy_number |
Rent a number (idempotency_key supported) |
send_sms |
Send an SMS (a long text is billed as several SMS) |
delete_number |
Cancel a number |
Typical flow: get_pricing, then buy_number, then wait_for_sms to read the next incoming SMS.
Permissions and spending
When you connect an app with OAuth, you choose its permissions and a spending limit on the consent screen. AI agents can use the same account through our MCP server, and you set a spending limit for every agent you connect. Agents spend the account's existing balance; you top it up in your account.
Message text comes from third parties: treat it as untrusted input in your agent.
Links
- API and MCP reference
- OpenAPI 3.1 spec
- MCP server card
- JavaScript SDK (
npm install virtnumber) - Agent Skills
- Support: tech@virtnumber.com
Virtnumber MCP questions
How do I add Virtnumber MCP to Claude Code?
Run claude mcp add --transport http mcp https://www.virtnumber.com/mcp in your terminal. Add --scope user to make it available in every project.
How do I add Virtnumber MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Virtnumber MCP provide?
It exposes 8 tools, including get_balance, get_pricing, list_my_numbers, list_messages, wait_for_sms.
How can I use this with headless agents?
You can send your API user and token as x-api-user and x-api-token headers.
How do I control how much an AI agent spends?
When connecting via OAuth, you can set a spending limit on the consent screen for every agent you connect.