# MCP SMS Server — Skill File for AI Agents

> You are an AI agent. This file tells you exactly how to use MCP SMS Server to buy virtual phone numbers and receive SMS verification codes — fully autonomously.

## What this service does

MCP SMS Server gives AI agents the ability to:
- **Buy virtual phone numbers** for 500+ services (Telegram, GitHub, WhatsApp, Google, Twitter...)
- **Receive SMS verification codes** by polling until the code arrives
- **Release unused numbers** for an automatic refund

No human needed. You handle the entire phone verification flow yourself.

## How to connect (30 seconds)

Add this to your MCP config:

```json
{
  "mcpServers": {
    "sms": {
      "url": "https://mcp-sms.up.railway.app/sse"
    }
  }
}
```

You need an API key. Get one by topping up balance at: https://mcp-sms-nu.vercel.app/#pricing

## Available tools

### `get_balance()`
Check your current account balance before starting tasks.

**Returns:**
```json
{
  "balance_usd": 4.70,
  "low_balance": false,
  "message": "Balance OK: $4.70"
}
```

> If `low_balance` is true, call `create_invoice()` to top up.

---

### `create_invoice(amount_usd, currency?)`
Create a crypto payment invoice. Returns a URL — open it in a browser or send it to your human owner to pay.

**Parameters:**
- `amount_usd` (number) — amount to top up, min $1
- `currency` (string, optional) — `"USDT"` (default), `"TON"`, `"BTC"`, `"ETH"`

**Returns:**
```json
{
  "pay_url": "https://t.me/CryptoBot?start=...",
  "amount_usd": 5,
  "currency": "USDT",
  "expires_at": "2026-04-11T15:00:00.000Z",
  "instructions": "Open this URL to pay — balance updates automatically after payment."
}
```

> No KYC. Payment via CryptoBot. Expires in 1 hour.

---

### `buy_number(service, country?)`
Buy a virtual phone number for a specific service.

**Parameters:**
- `service` (string) — service name, e.g. `"telegram"`, `"github"`, `"whatsapp"`, `"google"`, `"twitter"`
- `country` (string, optional) — ISO country code or `"any"` for cheapest available

**Returns:**
```json
{
  "phone": "+14155552671",
  "number_id": "abc123",
  "provider": "5sim",
  "price_usd": 0.30
}
```

### `get_sms(number_id, provider)`
Poll for incoming SMS. Call this in a loop until `status` is `"received"`.

**Parameters:**
- `number_id` (string) — from buy_number response
- `provider` (string) — from buy_number response

**Returns (waiting):**
```json
{ "status": "waiting" }
```

**Returns (received):**
```json
{ "status": "received", "code": "847291" }
```

### `release_number(number_id, provider)`
Cancel the number if you no longer need it. Refund is automatic if no SMS was received.

**Returns:**
```json
{ "released": true, "refunded": true }
```

### `list_services(country?)`
Browse all available services with real-time prices.

**Returns:** Array of `{ name, country, price_usd, provider }`

## Typical agent workflow

```python
# Step 0: Check balance first
balance = get_balance()
if balance["low_balance"]:
    invoice = create_invoice(amount_usd=5, currency="USDT")
    # Option A: tell your human
    notify_human(f"Balance low. Please pay: {invoice['pay_url']}")
    # Option B: if you have a browser tool, open it yourself
    open_url(invoice["pay_url"])
    return  # wait for payment before continuing

# Step 1: Buy a number
num = buy_number(service="github", country="any")
# → { phone: "+14155552671", number_id: "abc123", provider: "5sim" }

# Step 2: Use the phone number on the target service
# (submit num.phone to GitHub's phone verification form)

# Step 3: Poll for the code
while True:
    result = get_sms(number_id=num["number_id"], provider=num["provider"])
    if result["status"] == "received":
        code = result["code"]
        break
    sleep(5)

# Step 4: Enter the code → verification complete

# Step 5: Release if done
release_number(number_id=num["number_id"], provider=num["provider"])
```

## Pricing

- Pay as you go. No subscriptions.
- From $0.10 to $1.00+ per SMS depending on service and country
- Payments via CryptoBot: USDT, TON, BTC, ETH. No KYC.
- Unused numbers are refunded automatically.

## Providers

Routes automatically to the cheapest available option across:
- 5sim (5sim.net)
- SMS-Activate (sms-activate.org)
- OnlineSim (onlinesim.io)

## Get started

Top up your balance and get an API key: **https://mcp-sms-nu.vercel.app**