# sv-number/mcp-server [Health: Active]

**Category:** 💬 Communication  
**Repository:** https://github.com/sv-number/mcp-server  
**GitHub Stars:** 545  
**npm Downloads (last month):** 155  
**Views:** 2  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/mcp-server-160

## Description
Phone numbers for AI agents: order a private number, read the SMS verification code, hand it back.

## Tools
Capabilities this server exposes over MCP:

- **get_balance** — Current account balance. Ordering a number needs a funded balance; there is no free tier.
- **list_countries** — Every country the numbers can come from, with its id and operators. Use the id in order_number.
- **list_services** — Services available in a country, best match first. Order the code of the site you are registering with: a number bought for one service does not receive another service's SMS. Search by site name or domain, both work. The codes are arbitrary, so look them up instead of guessing: uk is Airbnb, not the United Kingdom. deliveredPercent is null when the pair has no statistics yet, which is the common case; then judge the pair by how many numbers are online. When the site is not in the catalogue at all, order notInList (ot), which receives SMS from any sender that is not in the list.
- **order_number** — Order a private number for one service in one country. The number is held for 20 minutes and belongs to this activation alone. Money is held now and charged when the code arrives. The service code has to be the one for the site you are registering with, otherwise its SMS goes to a different pool and never reaches you.
- **wait_for_code** — Wait for the verification code on an ordered number. Polls on its own and returns the code itself, already parsed out of the SMS. Trigger the SMS on the target service first.
- **finish_activation** — Close an activation after the code was used. Do this on every success: a forgotten activation holds money until it expires.
- **cancel_activation** — Cancel an activation when no code arrived; the money returns to the balance in full. Can be called right after ordering. If the API answers that it is too early, wait a couple of minutes and repeat.
- **request_another_sms** — Ask for one more code on the same number, for a password reset or a re-send. Works only after a first code has already arrived; before that the API refuses it.
- **totp_code** — Compute the authenticator code for an account whose second factor was set up with a shared secret. Runs locally by RFC 6238: the secret never leaves this machine.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "mcp-server": {
    "command": "npx",
    "args": ["-y","sv-number-mcp"],
    "env": {
      "SVN_API_KEY": "",
      "SVN_API_BASE": "",
      "SVN_LANG": "",
      "SVN_POLL_SECONDS": ""
    }
  }
}
```

**Requires environment variables:** `SVN_API_KEY`, `SVN_API_BASE`, `SVN_LANG`, `SVN_POLL_SECONDS` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What sv-number/mcp-server MCP server does

The sv-number/mcp-server MCP server gives an agent a workflow for obtaining temporary phone numbers and receiving verification codes through the SV Number API. It can inspect the account balance, browse supported countries and operators, search the service catalogue, and select a number for a specific service and country.

After an activation is ordered, the agent can wait for an incoming SMS and receive the code extracted from that message. Successful activations can be finished, while unwanted activations can be cancelled for a refund. The server can also request another SMS for an existing number and calculate an authenticator code locally using RFC 6238.

The service catalogue accepts a site name or URL. Results are ranked by match quality and include pricing, the number of currently available numbers, and—when statistics exist—the percentage of codes delivered for that service and country. The catalogue also identifies services that are not listed and can suggest alternatives.

## How it works

The server runs as a stdio MCP process and exposes nine tools. A typical sequence is to find the relevant service code, inspect countries or operators, order a number, wait for the code, and then finish or cancel the activation. `wait_for_code` polls at a controlled interval and stops when the number's 20-minute lifetime ends.

Each API request includes a language setting. That setting also controls the currency used in responses. The server checks textual API status markers before parsing responses and converts conditions such as unavailable numbers into guidance an agent can use. The API key remains in the process environment; tools and error messages do not return or quote it.

## Setup and configuration

Install the sv-number/mcp-server MCP server with the `sv-number-mcp` npm package through `npx`. Claude Code can register it with `claude mcp add`, while JSON-based clients such as Codex, Cursor, and Claude Desktop can define a command of `npx`, the `-y` and `sv-number-mcp` arguments, and the environment configuration.

`SVN_API_KEY` is required. Obtain the key from an SV Number user profile after registering, then fund the account before making API calls; the API has no free tier. Optional settings include `SVN_API_BASE`, which defaults to the documented handler endpoint, `SVN_LANG`, which defaults to `en`, and `SVN_POLL_SECONDS`, which defaults to `4`.

## Tools and capabilities

- `get_balance` reports remaining account credit.
- `list_countries` returns country identifiers and available operators.
- `list_services` searches by service name or domain and ranks matches.
- `order_number` requests a number for one service in one country.
- `wait_for_code` waits for and parses the received SMS code.
- `finish_activation` closes a successful activation.
- `cancel_activation` cancels an activation and requests a refund.
- `request_another_sms` asks for another message on the same number.
- `totp_code` computes an RFC 6238 authenticator code locally.

## Limitations and notes

The sv-number/mcp-server MCP server is intended for receiving verification SMS messages only. Its numbers do not send SMS, support calls, or provide a permanent conversational phone line. The README also excludes banking, payment, and government accounts from the intended use.

Service codes vary by catalogue and country, so agents should query `list_services` rather than rely on remembered codes. Delivery statistics may be absent for many service-country combinations; when available, they are more useful than price alone, while the live online count provides a fallback signal.

_Full upstream README: https://allmcps.com/mcp/mcp-server-160/readme_