smsverbot-mcp

smsverbot-mcp

面向 AI Agent 的短信验证码服务。 一个 MCP 服务，让 Agent 能购买真实电话号码、等待验证码，并在验证码始终未到时取消订单并获得退款。提供远程 streamable-HTTP 端点、预付余额、按量付费——无需订阅。

适用于 Claude Code、Cursor、VS Code、Codex、Hermes 和任何 MCP 客户端。关键词：MCP 服务、Model Context Protocol、短信验证、短信激活、虚拟号码、AI Agent、电话验证。

• 端点：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 密钥并显示余额。余额与机器人共用：只需充值一次，同一笔余额既可用于在聊天中购买号码，也可用于 Agent 购买号码。使用 MCP 无需单独账户、银行卡或加密货币钱包。

第 2 步——先试用免费沙盒

在同一菜单中点击 🧪 Тестовый режим。沙盒密钥可购买虚拟号码（+10000000000），并在约 4 秒后返回固定验证码 123456，完全免费，且不会调用真实服务商。免费构建和调试集成，准备好后再切换到真实密钥。

第 3 步——连接

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

徽章

---

一个为 AI Agent 提供号码以接收短信验证码的 MCP 服务。这是独立产品，与 Telegram 机器人无关。无需自带 UI 或 Web 框架即可运行：Agent 通过 stdio 或 streamable HTTP 连接并调用 MCP 工具。

资金以整戈比为单位存储。余额采用预付费模式：Agent 为账户充值，购买号码时扣除费用，取消时原额退款且仅退款一次。

30 秒快速连接（托管模式，无需安装）

端点：https://kremledroid.duckdns.org/mcp（streamable 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	每个密钥每天的请求限额（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 传输（streamable 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

第二条命令会将余额充值 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 模式时，请将 PROVIDER 和 FIVESIM_TOKEN 添加到 env 块中。

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 提供商，请在运行命令前通过 shell 传入环境变量。

Hermes 和其他 MCP 客户端

注册 stdio 服务，命令为 python，参数为 server.py --stdio；或者通过地址 http://127.0.0.1:8765/mcp 连接 HTTP 传输。通过 env 传入 MCP_DB，并在需要时传入 PROVIDER/FIVESIM_TOKEN。

工具

所有工具都将 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-клиента.