AI-Native MCP Server

SMSBulk MCP Server

Use SMSBulk straight from Claude Desktop, Cursor, or any MCP-compatible client — order SMS numbers and disposable email addresses and read back the codes.

The Model Context Protocol (MCP) lets AI assistants call external tools. This open-source server connects the SMSBulk API to your AI client, with no business logic and no secrets stored.

Open source on GitHub

What it does

The server is a pure relay: it forwards every request to the SMSBulk public API using your own API key. It exposes 18 tools across four groups — catalog, SMS, wallet, and email.

Unlike SMS-only providers, SMSBulk offers both phone and email verification. The email tools have no equivalent in most competing MCP servers.

Installation

Requires Node.js 18 or newer. Clone the repository, install dependencies, and build:

git clone https://github.com/Tolunay3434/smsbulk-mcp.git
cd smsbulk-mcp
npm install
npm run build

Then point your MCP client at the built dist/index.js. Catalog tools work without a key; every other tool needs your SMSBulk API key.

Client configuration

Claude Desktop

{
  "mcpServers": {
    "smsbulk": {
      "command": "node",
      "args": ["/absolute/path/to/smsbulk-mcp/dist/index.js"],
      "env": {
        "SMSBULK_API_KEY": "your_api_key_here",
        "MAX_SPEND_PER_SESSION": "5"
      }
    }
  }
}

Add this to claude_desktop_config.json, then restart Claude Desktop. The SMSBulk tools appear in the tools menu.

Cursor

{
  "mcpServers": {
    "smsbulk": {
      "command": "node",
      "args": ["/absolute/path/to/smsbulk-mcp/dist/index.js"],
      "env": {
        "SMSBULK_API_KEY": "your_api_key_here"
      }
    }
  }
}

Add this to ~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project).

Replace /absolute/path/to/smsbulk-mcp with the real path where you cloned the repository. Never commit your API key.

Tool reference

18 tools. Catalog tools need no key; all others send your x-api-key.

Catalog

No API key required

list_services—

All active services with stock and minimum-price summaries.

list_countries—

All supported countries with flags and ISO codes.

get_serviceslug

One service, looked up by SEO slug or service code.

get_service_countriesslug

In-stock countries for a service, with prices, stock, and speed tiers.

SMS verification

API key required

request_numberserviceCode, countryIso, operator?, idempotency_token?Spends

Reserve a number for SMS verification. Retry-guarded.

get_statusid

Status and SMS code (once received) for one activation.

completeid

Mark an activation complete. This is final.

cancelid

Cancel an activation; refunds the wallet if no SMS arrived.

request_resendid

Ask the provider to send another SMS to the same number.

list_activationslimit?, cursor?, status?

Your activations, cursor-paginated, newest first.

Wallet

API key required

get_balance—

Your current wallet balance.

list_transactionslimit?, cursor?

Recent deposits, debits, and refunds.

Email verification

API key requiredNot on SMS-only servers

email_get_domainssite

Available email provider domains for a target site, with prices and stock.

email_requestsite, domain, idempotency_token?Spends

Reserve a disposable email address. Retry-guarded.

email_listlimit?

Your recent email activations, newest first (up to 100, no cursor).

email_get_statusid

Status, parsed OTP, and raw HTML body (once received).

email_reorderidSpends

Re-open the same address for another OTP.

email_cancelid

Cancel; refunds the wallet if no OTP arrived.

Safety & limitations

These guards are convenience seatbelts, not guarantees.

Best-effort retry protection — not guaranteed idempotency

request_number and email_request keep a small in-memory guard that catches the common accidental case: the same order tool fired twice in one session with identical arguments replays the first result instead of charging again. It is not guaranteed idempotency — it lives only in this process's memory, resets on restart, does not coordinate across clients, and cannot prevent a true server-side race. To safely retry one intended order, pass the same idempotency_token; to deliberately place a second order, pass a different one.

Soft spend cap (MAX_SPEND_PER_SESSION)

When set, the server tracks the real cost of each successful order and blocks the next order once the running total reaches your cap. It is soft and in-memory — it resets on restart, covers this session only, and blocks the next request rather than splitting a single one. An order placed while still under the cap is allowed even if it pushes the total over. It is an extra layer on top of your account's server-side limits (balance, daily quota, rate limits).

Bring verification into your AI workflow

Clone the server, drop in your API key, and order SMS or email codes straight from your assistant.

View on GitHub Get an API key SMS API docs Email API docs