smsverbot-mcp

smsverbot-mcp

AI エージェント向け SMS 認証。 エージェントが実際の電話番号を購入し、確認コードを待ち、コードが届かない場合は返金を受けて注文をキャンセルできる MCP サーバーです。リモートのストリーミング可能な HTTP エンドポイント、プリペイド残高、従量課金制で、サブスクリプションはありません。

Claude Code、Cursor、VS Code、Codex、Hermes、その他あらゆる MCP クライアントで動作します。キーワード：MCP サーバー、Model Context Protocol、SMS 認証、SMS アクティベーション、仮想番号、AI エージェント、電話番号認証。

• エンドポイント：https://kremledroid.duckdns.org/mcp
• ツール：list_services、list_countries、get_price、buy_number、wait_for_code、cancel_order、get_balance、order_history、whoami

ステップ 1 — ボットでキーを取得する

Telegram で @Smsverbot を開き、🤖 MCP для агентов を押します（または /api_key を送信します）。ボットから API キーが発行され、残高が表示されます。残高はボットと共有されます。一度チャージすれば、チャットで購入した番号にも、エージェントが購入した番号にも同じ資金が使われます。MCP 用の別アカウント、カード、暗号資産ウォレットは不要です。

ステップ 2 — まず無料のサンドボックスを試す

同じメニューで 🧪 Тестовый режим を押します。サンドボックスキーでは、偽の番号（+10000000000）を購入でき、約 4 秒後に固定コード 123456 が返されます。費用はかからず、実際のプロバイダーにも接続しません。無料で統合を構築・デバッグし、準備ができたら実際のキーに切り替えてください。

ステップ 3 — 接続する

claude mcp add --transport http smsverbot https://kremledroid.duckdns.org/mcp

バッジ

---

AI エージェントに SMS 確認コードを受信するための番号を販売する MCP サーバーです。Telegram ボットとは別の製品です。独自の UI やウェブフレームワークなしで動作します。エージェントは stdio またはストリーミング可能な HTTP 経由で接続し、MCP ツールを呼び出します。

資金は整数のコペイカ単位で管理されます。残高はプリペイド方式です。エージェントがアカウントにチャージし、番号を購入すると料金が差し引かれ、キャンセルすると料金が一度だけ返金されます。

30 秒で接続（ホステッド、インストール不要）

エンドポイント：https://kremledroid.duckdns.org/mcp（ストリーミング可能な HTTP、TLS）。

Claude Code：

claude mcp add --transport http smsverbot https://kremledroid.duckdns.org/mcp

Cursor（~/.cursor/mcp.json）：

{ "mcpServers": { "smsverbot": { "url": "https://kremledroid.duckdns.org/mcp" } } }

VS Code（.vscode/mcp.json）：

{ "servers": { "smsverbot": { "type": "http", "url": "https://kremledroid.duckdns.org/mcp" } } }

次に、Telegram ボット @Smsverbot で API キーを取得し、残高をチャージして、次のいずれかの方法でキーを渡します。ホステッドモードでは、クライアント設定の Authorization: Bearer <ключ> ヘッダーを使う方法を推奨します。または、任意のツールの最初の引数 api_key として渡します。キーが受け付けられたことは、ツール whoami で確認できます。このツールは key_id と残高を返します。

機能

• カタログ、料金、購入、コード待機、キャンセル、残高、履歴、キー確認のための 9 つの MCP ツール。
• プロバイダーに依存しないレイヤー：ネットワーク接続不要の決定論的な mock と、実際の fivesim アダプター。
• 残高に関するすべての操作で、WAL と BEGIN IMMEDIATE トランザクションを使用する SQLite。
• API キーは SHA-256 形式でのみ保存されます。平文のキーが表示されるのは一度だけです。
• キャンセル時の冪等な返金。
• キーごとのレート制限と日次上限。

インストール

Windows（PowerShell または cmd）：

python -m venv .venv
.venv/Scripts/pip install -r requirements.txt

Linux/macOS：

python -m venv .venv
.venv/bin/pip install -r requirements.txt

Python 3.11 以降が必要です。プロジェクトは Python 3.14 でテストされています。

セットアップ

.env.example を .env にコピーし、値を入力してください。.env ファイルは自動的に読み込まれ、環境変数が優先されます。

変数	デフォルト	用途
MCP_DB	./mcp.db	SQLite データベースへのパス
MCP_API_KEY	空	api_key が空で渡された場合に stdio クライアントに使用するデフォルトキー
PROVIDER	mock	mock または fivesim
FIVESIM_TOKEN	空	5sim のトークン。fivesim では必須です
MCP_MARKUP	2.5	仕入れ価格への上乗せ率
RATE_LIMIT_PER_15MIN	20	15 分あたりのキーごとの購入上限
DAILY_CODE_LIMIT	200	キーごとの 1 日あたりのリクエスト上限（UTC）
CODE_WAIT_SECONDS	120	SMS コードの最大待機時間
USD_KOP_RATE	9200	USD→RUB の為替レート（ドルあたりのコペイカ）

リポジトリに秘密情報はありません。.env や実際のトークンをコミットしないでください。

起動

Mock モードではネットワークリクエストを行わないため、テストやローカル開発に適しています。

.venv/Scripts/python server.py --stdio

Live モードは明示的に有効にした場合のみ起動します。

set PROVIDER=fivesim
set FIVESIM_TOKEN=your_token_here
.venv/Scripts/python server.py --stdio

HTTP トランスポート（ストリーミング可能な HTTP）：

.venv/Scripts/python server.py --http --port 8765

デフォルトでは HTTP は 127.0.0.1 でリッスンします。ホストは --host で変更できます。

キーとチャージ

公開 API キーが表示されるのは作成時のみです。データベースには SHA-256 のみが保存されます。

.venv/Scripts/python server.py --create-key "my-agent"
.venv/Scripts/python server.py --topup svb_ВАШ_КЛЮЧ 500

2 つ目のコマンドでは、残高に 500 ルーブル（50000 コペイカ）がチャージされます。

管理者：キーの発行

admin.py は MCP_DB からデータベースへのパスを読み込みます（デフォルトは ./mcp.db）。

ラベル付きのキーを作成し、残高に 500 ルーブルをすぐにチャージします。

python admin.py create --label client1 --topup 500

すべてのキーを表示します（ID、ラベル、ルーブル建ての残高）。

python admin.py list

キーの残高に 200 ルーブルをチャージします。

python admin.py topup --key-id ID --amount 200

キーの最近の注文を表示します。

python admin.py orders --key-id ID

公開 API キーが表示されるのは、作成時の一度だけです。

MCP クライアントへの接続

すべての例で、パスを server.py への絶対パスに置き換えてください。Live モードを使う場合は、env ブロックに PROVIDER と FIVESIM_TOKEN を追加してください。

Claude Desktop

ファイル claude_desktop_config.json：

{
  "mcpServers": {
    "smsverbot": {
      "command": "C:/path/to/.venv/Scripts/python.exe",
      "args": ["C:/path/to/smsverbot-mcp/server.py", "--stdio"],
      "env": {
        "MCP_DB": "C:/path/to/smsverbot-mcp/mcp.db",
        "PROVIDER": "mock"
      }
    }
  }
}

Cursor

ファイル .cursor/mcp.json（またはグローバル設定の ~/.cursor/mcp.json）では、Claude Desktop と同じ mcpServers スキーマを使用します。

Claude Code

claude mcp add smsverbot -- python server.py --stdio

公開 HTTP サーバー：

claude mcp add --transport http smsverbot https://kremledroid.duckdns.org/mcp

専用のデータベースと Live プロバイダーを使用する場合は、コマンドを実行する前にシェルで環境変数を設定してください。

Hermes とその他の MCP クライアント

コマンド python と引数 server.py --stdio を使って stdio サーバーを登録するか、http://127.0.0.1:8765/mcp で HTTP トランスポートに接続してください。MCP_DB と、必要に応じて PROVIDER／FIVESIM_TOKEN を env 経由で渡してください。

ツール

すべてのツールは、最初の引数として api_key を受け取ります。空の文字列を渡すと、環境変数の MCP_API_KEY が使用されます。成功時は {"ok": true, ...}、エラー時は {"ok": false, "error": "CODE", "message": "..."} が返されます。エラーコード：UNAUTHORIZED、INSUFFICIENT_FUNDS、RATE_LIMITED、DAILY_LIMIT、ORDER_NOT_FOUND、NO_NUMBERS、UNAVAILABLE、UPSTREAM_ERROR、INTERNAL。

ツール	説明
list_services(country="indonesia")	利用可能なサービスの一覧
list_countries	利用可能な国の一覧
get_price(service, country)	購入や残高の引き落としを行わずに小売価格を取得
buy_number(service, country)	電話番号を購入して残高から引き落とし
wait_for_code(order_id)	注文の SMS コードを待機
cancel_order(order_id)	注文をキャンセルし、一度だけ返金
get_balance()	コペイカおよびルーブル建ての現在の残高
order_history(limit=10)	キーの最近の注文
whoami	キーを確認：key_id とルーブル建ての残高

カタログ、価格、残高、履歴の参照で料金が引き落とされることはありません。

Биллинг

• Все суммы хранятся и списываются в целых копейках; денежные операции не используют float.
• Закупочная цена cost_kop берётся у провайдера.
• Розничная цена: price_kop = max(ceil(cost_kop * MCP_MARKUP), cost_kop + 1000), затем округление вверх до 100 копеек.
• Покупка: сначала создаётся заказ в статусе waiting, затем баланс списывается атомарно. При нехватке средств заказ отменяется у провайдера и помечается cancelled.
• wait_for_code только опрашивает провайдера. Таймаут переводит ответ в pending, деньги не возвращаются.
• Отмена возвращает полную розничную цену, если заказ был в статусе waiting/open. Повторная отмена возвращает refunded_kop: 0.
• Каждое изменение баланса фиксируется в таблице ledger: topup, debit, refund.

Лимиты

• RATE_LIMIT_PER_15MIN — скользящее окно на ключ, по умолчанию 20 запросов покупки за 15 минут.
• DAILY_CODE_LIMIT — число незавершённых отменой заказов на ключ за сутки UTC, по умолчанию 200.
• CODE_WAIT_SECONDS — максимум ожидания кода, по умолчанию 120 секунд; опрос каждые 2 секунды.
• Таймаут ожидания не освобождает номер и не возвращает деньги; для возврата вызовите cancel_order.

AUP: допустимое и запрещённое использование

Разрешено:

• легальная регистрация и подтверждение собственных аккаунтов;
• автоматизация тестирования собственных продуктов;
• сценарии, где использование временного номера не нарушает правила сервиса и законодательство.

Запрещено:

• мошенничество, спам, обход банов и массовое создание фейковых аккаунтов;
• покупка номеров для преступлений или нарушения законов;
• перепродажа доступа способом, скрывающим конечного пользователя от проверки;
• использование сервиса лицами младше установленного законом возраста.

Оператор вправе заблокировать ключ и отказать в обслуживании при нарушении AUP. Пользователь обязан соблюдать правила целевых сервисов, включая их ограничения на виртуальные номера.

Проверка

.venv/Scripts/python -m pytest -q tests/
.venv/Scripts/python -m compileall -q .

Тест tests/test_mcp_client.py запускает сервер по stdio через официальный MCP-клиент, проверяет ровно 9 инструментов и читает баланс из общей тестовой базы.

Структура

• config.py — настройки из окружения.
• store.py — SQLite, ключи, заказы, ledger, лимиты.
• providers/ — протокол, mock- и 5sim-адаптеры.
• service.py — бизнес-логика цен, покупки, ожидания и отмены.
• server.py — FastMCP, 9 инструментов и CLI.
• admin.py, admin_service.py — админ-CLI и операции с ключами в рублях.
• tests/ — сервисные тесты и интеграционный тест MCP-клиента.