sv-number MCP Server: Give AI Agents a Phone Number to Receive SMS Verification Codes

What problem this server solves for AI agents

Many services require a phone number for account creation or two-factor authentication verification. When an AI agent needs to create an account on such a service during an automated workflow, it has no phone number of its own. Hardcoding a real personal number into an agent's environment is a privacy problem. Using a number already claimed by a different account fails verification.

The sv-number MCP server solves this by giving agents a tool-level interface to a commercial phone number API covering 200+ countries. The agent calls three tools in sequence: order_number to get a temporary private number, wait_for_code to block until the SMS arrives and return the parsed verification code, and finish_activation to close the activation and end billing. The whole workflow fits inside a single agent turn.

The server communicates over stdio, which is the standard MCP transport. Any MCP-compatible host, including Claude Code, Claude Desktop, Cursor, and Codex CLI, can attach it. No SDK is needed beyond the npx invocation that launches the server process.

The nine tools and how they chain together

The README describes nine tools:

get_balance shows the remaining credit on the account. list_countries returns every country with its numeric id and operator options. list_services searches by service name or domain and returns ranked matches with price, live pool size, and the delivery rate (deliveredPercent) for each service-and-country combination.

order_number takes a service code and a country id and returns a real phone number. wait_for_code polls until the code arrives, already parsed out of the full SMS text, and returns the code string. finish_activation closes a successful activation. cancel_activation cancels and refunds the balance. request_another_sms asks the number to receive one additional code on the same activation. totp_code computes a time-based authenticator code locally from a seed, following RFC 6238, without any network call.

The README gives this concise example of the core workflow:

order_number(service="tg", country=6)   ->  +62 838 1234 5678
wait_for_code(activationId)             ->  123456
finish_activation(activationId)         ->  done

Service codes are arbitrary and must not be recalled from memory. The README states examples: uk is Airbnb, re is Coinbase, tn is LinkedIn. The list_services tool returns the correct code by name or domain search, so an agent should always call list_services to find the code rather than hardcoding it.

The deliveredPercent field is the historical delivery rate for a given service-and-country pair, and null when no statistics exist yet. The README advises picking by delivery rate when a value is available, and by the online pool size (how many numbers are currently ready) when it is not.

Installing the server in Claude Code and other MCP hosts

For Claude Code, the README gives a single installation command:

claude mcp add sv-number --env SVN_API_KEY=your_key_here -- npx -y sv-number-mcp

This registers the server under the name sv-number, injects the API key into the server's environment, and uses npx to run the latest published package without a local install step.

For any host that reads a JSON configuration file, including Cursor and Claude Desktop:

{
  "mcpServers": {
    "sv-number": {
      "command": "npx",
      "args": ["-y", "sv-number-mcp"],
      "env": { "SVN_API_KEY": "your_key_here" }
    }
  }
}

The API key is obtained from the account profile on sms-verification-number.com after signup. The README notes that the balance must be funded before ordering numbers: there is no free tier. The key is read from the SVN_API_KEY environment variable inside the server process and is never returned in tool outputs or error messages.

The server also accepts three optional environment variables: SVN_API_BASE (the API endpoint, defaulting to the production handler URL), SVN_LANG (the language and currency for responses, defaulting to en), and SVN_POLL_SECONDS (the polling interval for wait_for_code, defaulting to 4 seconds).

Error handling and what the server adds beyond raw API calls

The README describes several behaviours the server adds on top of the raw API, which matter for agent reliability.

Every outbound call includes the lang parameter. Without it, the API prices responses in a different currency. The server never omits this parameter regardless of the calling agent's configuration.

The API returns text markers instead of JSON for certain error states. The server catches these before attempting JSON parsing and turns them into actionable messages. For example, NO_NUMBERS becomes the message "change country, or set operator to any" so the agent has a concrete next step rather than a token it must interpret.

The wait_for_code tool polls at the configured SVN_POLL_SECONDS interval rather than hammering the status endpoint on every available tick. It stops automatically after the 20-minute activation lifetime expires, which prevents an agent from waiting indefinitely.

For services that require two-step authentication (password then authenticator code), the totp_code tool computes the 6-digit TOTP value locally from a seed string, without any API call. This means an agent can handle authenticator-app flows in the same session without switching to a different service.

What the server cannot do

The README is direct about the scope boundary: receiving verification codes is the entire job. Numbers ordered through sv-number cannot send SMS messages. They do not receive voice calls. They are not intended for banking verification, payment account registration, or government portals. The README states these explicitly as out of scope.

Numbers are temporary. The activation window is 20 minutes, as documented in the wait_for_code polling limit. An agent that needs a permanent number to hold a conversation, receive follow-up messages, or accept two-factor authentication on an ongoing basis should use a carrier product rather than an SMS verification service.

The service codes are country-specific. A service may appear in the catalogue for one country but not for another. list_services will note when a service is unavailable in the selected country and suggest trying a different country. The ot code ("Not on list") acts as a fallback that accepts SMS from any sender not in the main catalogue, but it is not a wildcard: a service with its own code will only deliver to that specific code.

Comparison with direct API integration

The direct alternative to this MCP server is calling the sms-verification-number.com REST API directly from agent code. The difference is integration depth. A direct API integration requires the agent developer to handle HTTP calls, parse responses, implement polling with appropriate intervals, interpret the text-marker error states, and inject the lang parameter correctly. The MCP server handles all of these at the transport layer.

For an agent developer using an MCP-compatible host, the server eliminates integration code entirely. The agent gets nine pre-tested tools that behave consistently across providers. For a developer building a custom agent runtime without MCP support, the direct API path is the only option since the server communicates over stdio.

The README notes the server is also available as a markdown skill at https://github.com/sv-number/skills for use in contexts where an MCP server cannot be deployed but a skill file can be loaded into the agent's context.

Maintenance, dependencies, and licence

The last push to the repository was on 2026-08-10. The repository is not archived. There are no GitHub releases; the package is published to npm as sv-number-mcp at version 1.0.2 as of the package.json in the repository.

The server is built on Node.js 18 or later and depends on two production packages: @modelcontextprotocol/sdk (version ^1.0.0) and zod (version ^3.23.8) for input validation. There are no other production dependencies.

The code is MIT-licensed. The README explicitly notes that the service behind the API is commercial. Using the server in a project is free; funding an account balance and paying for phone number activations is not.

Editorial conclusion

The sv-number MCP server is the right tool for AI agents that must complete phone-based account verification during automated workflows, particularly when the target service expects a number from a specific country. It is not the right tool for banking verification, payment accounts, government portals, or any workflow that needs a permanent phone number for ongoing use. Before funding an API balance, run list_countries to confirm the target country is in the catalogue and list_services to confirm the target service has available numbers with a reasonable deliveredPercent.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Project website
4. README
5. sv-number/mcp-server on GitHub