Model or dataset
sv-number/mcp-server avatar
sv-number/mcp-server

sv-number-mcp: a /stubs/ default base URL, a key on the command line, and a currency switch

MCP server for AI agents that need a phone number: order a private number in 200+ countries, read the SMS verification code, hand it back. The widest country coverage in the category, and you can check it with one API call.

522 stars7 forksJavaScriptMIT

At a glance

What is it?
sv-number-mcp is an MCP wrapper over a commercial SMS activation service, built so an automated caller can order a number and receive a one-time code. Its configuration and its data quality are more interesting than its nine-tool surface, and its abuse surface is inherent to what it sells.
Who is it for?
Use this only where receiving a one-time code by SMS is the legitimate mechanism, such as your own test accounts and your own integration testing, and never for accounts you do not own, for creating accounts at volume, or for anything financial or government related, which the project rules out itself.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository received new commits within the last day.
What is it written in?
Mainly JavaScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • sv-number/mcp-server522 ★ · -33
Star history
Repository2026-09-112026-11-15
sv-number/mcp-server555522

-33 Stars in the last 65 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

Nine tools wrapping a text-token API whose default base URL ends in stubs

The runtime surface is deliberately small. There are two dependencies: the Model Context Protocol SDK and zod. There are nine tools over stdio, and no SDK to learn.

Underneath, the protocol is older than that. The configuration table gives the default base URL as `https://sms-verification-number.com/stubs/handler_api`, a path that names itself a stub, while the API reference the page links to lives at a different path. The upstream speaks text markers rather than JSON, and the server checks for those markers before anything is parsed, turning them into sentences an agent can act on: `NO_NUMBERS` becomes an instruction to change country or set operator to any, rather than a bare token.

That translation layer is the actual engineering in this project. It also explains the other adaptation. The polling loop is described as running at a sane interval instead of hammering the upstream status call, and the status method is named in upstream camelCase, which is a strong hint about the shape of the API being wrapped.

So this is not an implementation of SMS activation. It is a JSON-shaped adapter over a commercial reseller whose protocol predates JSON, plus a decision about which errors deserve to be readable by a language model.

The language parameter sets the currency too, and omitting it fails without an error

There are four configuration variables. `SVN_API_KEY` is required. `SVN_POLL_SECONDS` defaults to `4`. `SVN_LANG` defaults to `en`. And `SVN_API_BASE` carries the stub path described above.

The interesting one is `SVN_LANG`, because it is described as setting both the language and the currency of the answers. The reasoning is given: every call carries `lang`, the upstream API answers without it, but then it prices in another currency, so the server never leaves it out.

That is a sensible fix for a real inconsistency, and it moves the failure mode somewhere quiet. The parameter does two unrelated jobs, so a value that looks like a locale setting also selects a denomination. If a caller constructs a request without it, or with a value the reseller does not recognise, the response does not fail, it simply prices in a different currency than the operator expects. There is no error to catch.

For an agent-driven client the risk is concrete. The server is careful to always send `lang`, so a well-behaved path is fine. The exposure is any path that talks to the upstream directly, or any future change to how the value is chosen, because a silent denomination switch produces plausible-looking prices in the wrong unit rather than a diagnostic.

The delivery rate is missing for most pairs, so whether a code arrives is unforecastable

The service catalogue is meant to let an agent choose well before spending money, and one of its fields is the honest weak point.

`deliveredPercent` is described as the delivery rate for a service and country pair, and it is `null` when that pair has no statistics yet. The page then says that this is the common case. The stated guidance is to pick by that rate where a number exists, and otherwise to fall back to `online`, which shows how big the live pool is, described as the next best signal.

So in the majority of cases the primary quality metric is absent and the substitute is pool size, which tells you how many numbers are available and nothing about whether an SMS will arrive.

Two timing figures bound the attempt. `wait_for_code` polls until the code lands, at the default interval of four seconds, and stops at the 20 minute life of a number. That is a ceiling on the order of 300 polls for one attempt. `cancel_activation` cancels and refunds, and `request_another_sms` asks for one more code on the same number.

Put together with the null delivery rate, the arithmetic is why this class of tool gets used in bulk rather than once: an unpredictable per-attempt success rate combined with a per-number cost and a refund on cancel pushes any serious caller toward many attempts across many countries, which is exactly the pattern the project's own exclusions are trying to rule out.

The catch-all code is documented as a fallback and not a wildcard

The catalogue has a fallback entry, `ot`, described as Not on list, which receives SMS from any sender that is not in the list. That sentence reads like a universal receiver.

The next sentence removes it. A site that has its own code sends to that code, so `ot` is a fallback and not a wildcard. In other words, you cannot use the catch-all to intercept a code from a named service, because the reseller routes by code and the named service has one.

That constraint lives in the upstream service, not in this client, which means no configuration change here lifts it. It is the single most important limit on what the nine tools can be used for, and the page states it plainly rather than leaving it to be discovered.

The second boundary is in a section titled What it is not. Receiving verification codes is the whole job: these numbers do not send SMS, do not take calls, and are not meant for banking, payment or government accounts. An agent that needs a permanent number to hold a conversation is told to want a carrier product instead.

Both statements narrow the surface rather than expand it. Receive-only rules out two-factor registration of your own accounts by SMS, the no-outgoing rule rules out anything that needs a reply, and the financial and government exclusions rule out the categories where a code is a bearer credential for real money.

The one worked example is a messaging account code

Three lines at the top of the page show the intended flow.

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

The example orders a number for service `tg` in country `6`, receives a `+62` number, waits for a code, and closes the activation. Country 6 is the Indonesian country code, and `tg` is the short code for a messaging service, so the single documented happy path is an agent completing SMS verification for a messaging account.

The catalogue guidance sits next to it with a warning that matters more than it first appears: codes are arbitrary and must never be recalled from memory. The examples given for that warning name a travel marketplace, a cryptocurrency exchange, and a professional network.

So the tool is explicitly pointed at account types where a received SMS is a login credential, and the warning is about correctness rather than about permission. The page does not frame account verification as a use to be careful with, and there is no section on what the resulting number could be used for after the code is read.

What is missing is any statement about volume. Coverage across 200+ countries is the headline claim and the one the page invites you to verify by counting rows, and nothing in the documentation sets a limit on how many activations a single account or key may run.

One install path puts the API key on the command line and into shell history

There are three ways in, and they are not equally careful with the credential.

The command line form passes the key inline as an environment assignment:

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

That puts the key into your shell history, into the argument vector of the running process where any local process can read it, and into whatever Claude Code stores as a saved server definition.

The JSON form is better. It puts the key in an `env` object inside the server configuration, which at least keeps it out of the process arguments:

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

The page then makes a claim about the key that holds for both paths and is worth crediting: it is read from the environment and never leaves the process, no tool returns it, and no error message quotes it. Given that the API can be pointed anywhere through `SVN_API_BASE`, that is a real design decision rather than a default.

The gap is on the way in, not on the way through. Both documented snippets also carry a literal `your_key_here` placeholder, which is exactly what people leave in place when they copy first and fill in later, and the page says the balance has to be funded because there is no free tier on this API. A key on a funded account is worth rotating if it lands in a log.

Version 1.0.2 with no releases, no lockfile, and three registry descriptors at the root

The repository has no published releases, and the package manifest declares version `1.0.2`. So the version a user gets from the registry is the only version record, and there is no tag to diff against or to pin to.

The last push is 2026-08-10, and the project is small: seven forks and no open issues against roughly five hundred stars, with three source-adjacent directories at the root and a single `src` tree.

There is no lockfile in the root listing. The container build copies `package.json` and `tsconfig.json`, copies `src`, runs `npm install`, and starts `node dist/index.js` from `node:20-alpine`. With no lockfile, that install resolves the declared ranges afresh each time, so two builds of the same commit can pick different patch releases of the SDK and zod. The manifest declares an engines floor of Node 18 while the image pins the Node 20 line, so the container is narrower than the package promises.

The root also carries three separate registry descriptors, `glama.json`, `server.json`, and `manifest.json`, plus a `pack.sh` packaging script and an `assets` directory. The manifest declares an `mcpName` of `io.github.sv-number/mcp-server` and a binary of `sv-number-mcp`, so the same artefact presents three identifiers depending on where you meet it. Nothing visible states that the three descriptors are generated from the package manifest, which means drift between them is something you would have to check by hand.

One of the nine tools is a local TOTP calculator with no key and no network

The tool list mixes two unrelated jobs. Eight tools are the SMS activation workflow: balance, country list, service catalogue, order, wait, finish, cancel, request another SMS.

The ninth is `totp_code`, described as computing the authenticator code locally by RFC 6238. It needs no API key, no balance, and no network. It is a standard one-time-password calculation over a shared secret.

That makes it the one tool here that is safe in a way the rest are not, and it is bundled anyway. Nothing is wrong with including it, and a client that wants both kinds of code has one dependency. But it is worth separating the two when you reason about risk: this package is not only a paid number broker.

`wait_for_code` is the mirror image. It does not just wait, it parses: the code is returned already extracted from the SMS body. So the extraction happens server-side, against message formats that the upstream does not control and that change without notice. A message whose wording shifts would return an empty or wrong code rather than an error, and the caller cannot tell the difference between a parse failure and a slow network.

The same product also ships as a markdown skill in a separate repository, which is a reasonable distribution choice for a small tool and one more artefact to keep in step.

Editorial conclusion

Use this only where receiving a one-time code by SMS is the legitimate mechanism, such as your own test accounts and your own integration testing, and never for accounts you do not own, for creating accounts at volume, or for anything financial or government related, which the project rules out itself. Before you wire it into an agent, read the configuration table rather than the install snippet, because the command line form puts your API key into shell history and process arguments while the JSON form does not. Then set the language variable deliberately, since it controls the currency as well as the response language and omitting it does not error. And budget for the retry behaviour: the delivery rate is usually unknown, so plan for more attempts than you expect and check the terms of the service behind the free client.

Frequently asked questions

What does the sv-number-mcp server do?

It wraps a commercial SMS activation service in nine MCP tools over stdio. An agent orders a private number for one service in one country, polls until the SMS code arrives, and closes or cancels the activation. There is no free tier, so the account balance has to be funded.

What configuration variables does sv-number-mcp accept?

SVN_API_KEY is required. SVN_API_BASE defaults to https://sms-verification-number.com/stubs/handler_api. SVN_LANG defaults to en and sets both the language and the currency of the answers. SVN_POLL_SECONDS defaults to 4.

What can these phone numbers not be used for?

Receiving verification codes is the whole job. The numbers do not send SMS, do not take calls, and are not meant for banking, payment or government accounts. The catch-all `ot` code receives messages only from senders that have no code of their own, so it cannot be used to intercept a named service.

How does the service catalogue rank results?

list_services takes a site name or a URL and answers with matches ranked best first plus a notInList fallback, so discord.com finds Discord. It ranks a whole word above a substring, reports price, how many numbers are online, and a deliveredPercent delivery rate that is null when the pair has no statistics, which the page says is the common case.

How do I install sv-number-mcp?

In Claude Code with `claude mcp add sv-number --env SVN_API_KEY=your_key_here -- npx -y sv-number-mcp`, or by adding a server entry with command npx, args -y sv-number-mcp and an env object containing SVN_API_KEY to a JSON config used by Codex, Cursor or Claude Desktop.

Is the sv-number-mcp package versioned with releases?

No GitHub releases are published. The package manifest declares version 1.0.2, and the last push to the repository is 2026-08-10. The project is MIT licensed, and the documentation notes that the service behind the client is commercial.

Official sources

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

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/sv-number-mcp-server.svg)](https://hysenlabs.com/projects/sv-number-mcp-server)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/sv-number-mcp-server.svg)](https://hysenlabs.com/projects/sv-number-mcp-server)

Was this useful?