SMS.ir MCP сервер

Локальный сервер Model Context Protocol, который предоставляет подобранный, защищённый набор инструментов для API панели SMS.ir V2. Создан на Python + FastMCP.

• Транспорт stdio для Codex / Claude Desktop / Claude Code

• Транспорт streamable HTTP для локальной разработки и тестирования

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

• Номера телефонов, текст сообщений, ключи API и OTP-коды маскируются в логах.

Создано на основе коллекции Postman SMS.ir Panel V2 (не включена в этот репозиторий — она содержит реальный ключ API). Нормализованное описание API находится в docs/API.md и docs/openapi.yaml.

1. Установка

Требуется Python 3.10+ (разработано и протестировано на CPython 3.12).

cd C:\Users\Kasra\Documents\sms.ir-mcp

# create the project-local virtual environment
py -3.12 -m venv .venv

# install runtime deps (pinned)
.\.venv\Scripts\python.exe -m pip install -r requirements.txt

# ...or install with the package + dev/test extras
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"

Related MCP server: meta-mcp-py

2. Конфигурация

Вся конфигурация берётся из переменных окружения. Для локального использования скопируйте пример файла env и заполните его — он игнорируется git и никогда не коммитится:

copy .env.example .env
notepad .env

Реальные переменные окружения всегда имеют приоритет над значениями из файла env.

3. Запуск

# stdio (what MCP clients launch)
.\.venv\Scripts\python.exe -m sms_ir_mcp --transport stdio

# streamable HTTP for local testing (http://127.0.0.1:8000/mcp)
.\.venv\Scripts\python.exe -m sms_ir_mcp --transport http --host 127.0.0.1 --port 8000

Для быстрой проверки подключения и аутентификации, которая никогда не тратит кредиты, вызовите инструмент health_check (или get_balance) из любого подключённого клиента — оба используют GET /v1/credit под капотом.

4. Инструменты

Инструменты только для чтения доступны всегда. Инструменты записи требуют confirm=true и SMSIR_ALLOW_SEND=true; разрушительный инструмент требует confirm=true.

Каждый инструмент возвращает {"ok": true, "data": …, …} при успехе или {"ok": false, "error": {"code": …, "message": …}} при ошибке. Коды ошибок: config_error, validation_error, confirmation_required, send_disabled, auth_error, rate_limited, transient_error, api_error, internal_error.

Примеры

// check balance
get_balance() -> {"ok": true, "data": {"credit": 45210}}

// read the latest OTP received on a given number
extract_latest_otp({"mobile": "9821000"})
  -> {"ok": true, "data": {"otp": "834122", "matched": true, "from": "*****1000", ...}}

// attempt a send without confirming -> refused, nothing sent
send_sms({"message_text": "Hi", "mobiles": ["09121234567"]})
  -> {"ok": false, "error": {"code": "confirmation_required", ...}}

// confirmed send, but kill switch still off -> refused, nothing sent
send_sms({"message_text": "Hi", "mobiles": ["09121234567"], "confirm": true})
  -> {"ok": false, "error": {"code": "send_disabled", ...}}

// edited .env to set SMSIR_ALLOW_SEND=true -> apply it without restarting
reload_config()
  -> {"ok": true, "data": {"config": {"allow_send": true, ...}, "changed": ["allow_send"]}}

// with SMSIR_ALLOW_SEND=true AND confirm=true -> actually sends (billable)
send_sms({"message_text": "Hi", "mobiles": ["09121234567"],
          "line_number": "30007732000000", "confirm": true})
  -> {"ok": true, "data": {"packId": "…", "messageIds": [123], "cost": 1.0}, "recipients": 1}

5. Модель безопасности

• Платные операции (send_sms, send_verification_code, send_personalized_sms) требуют оба условия:

  1. confirm=true в вызове инструмента, и

  2. SMSIR_ALLOW_SEND=true в окружении сервера. При выключенном аварийном выключателе подтверждённый вызов всё равно ничего не отправляет.

• Разрушительная операция (cancel_scheduled_send) требует confirm=true.

• Нет произвольных базовых URL: принимается только api.sms.ir, если SMSIR_ALLOW_CUSTOM_BASE_URL=true. HTTPS обязателен.

• Нет инъекции заголовков: вызывающие не могут устанавливать заголовки запросов; передаются только типизированные, проверенные поля.

• Таймауты + ограниченные повторы + клиентское ограничение частоты на каждом запросе.

• Маскирование: ключи API, номера телефонов, тела сообщений и значения OTP маскируются в выводе логов.

• Нет административных конечных точек: доступны только операции из коллекции Postman; ничего для управления аккаунтом/конфигурацией.

6. Регистрация клиента

Ваш реальный ключ API помещается в .env в этой папке — никогда в файл конфигурации клиента. Каждая конфигурация ниже только указывает клиенту на этот сервер и его .env.

Codex CLI (установлен)

codex mcp add sms-ir `
  --env SMSIR_ENV_FILE=C:\Users\Kasra\Documents\sms.ir-mcp\.env `
  -- C:\Users\Kasra\Documents\sms.ir-mcp\.venv\Scripts\python.exe -m sms_ir_mcp --transport stdio

codex mcp list          # sms-ir should appear
codex mcp get sms-ir

Ручной эквивалент: docs/codex_config.example.toml.

Claude Code (установлен)

Этот репозиторий содержит проектный .mcp.json. Откройте Claude Code в этом каталоге и подтвердите сервер sms-ir при запросе:

cd C:\Users\Kasra\Documents\sms.ir-mcp
claude
/mcp                    # shows sms-ir and its tools

Чтобы зарегистрировать его на уровне пользователя вместо этого:

claude mcp add sms-ir --scope user `
  --env SMSIR_ENV_FILE=C:\Users\Kasra\Documents\sms.ir-mcp\.env `
  -- C:\Users\Kasra\Documents\sms.ir-mcp\.venv\Scripts\python.exe -m sms_ir_mcp --transport stdio

Claude Desktop (не установлен)

Когда установлен, объедините docs/claude_desktop_config.example.json в %APPDATA%\Claude\claude_desktop_config.json (сначала сделайте резервную копию; сохраните другие серверы).

7. Разработка

.\.venv\Scripts\python.exe -m ruff check src tests
.\.venv\Scripts\python.exe -m ruff format --check src tests
.\.venv\Scripts\python.exe -m pytest

Тесты покрывают построение запросов, заголовок аутентификации, разбор конверта, нормализацию ошибок, повторы/ограничение частоты, проверку аргументов, маскирование, извлечение OTP, мокированную интеграцию для каждого инструмента (с использованием примеров полезных нагрузок из Postman), согласованность OpenAPI с коллекцией и обнаружение инструментов MCP.

8. Первый живой тест (после предоставления учётных данных)

Ничто в этом репозитории не совершало платных вызовов. Чтобы выполнить первую реальную отправку, которую вы явно авторизуете:

1. Поместите ваш ключ в .env:

   SMSIR_API_KEY=<your real key>
   SMSIR_DEFAULT_LINE_NUMBER=<your approved line>
   SMSIR_ALLOW_SEND=true

2. Проверьте подключение без трат — из подключённого клиента вызовите health_check (или get_balance).

3. Затем, и только затем, выполните первый платный вызов. Точный вызов инструмента:

   send_sms({
     "message_text": "SMS.ir MCP test",
     "mobiles": ["<your own mobile>"],
     "line_number": "<your approved line>",
     "confirm": true
   })

   Формулировка для Codex: "Используй инструмент send_sms сервера sms-ir, чтобы отправить 'SMS.ir MCP test' на <ваш собственный мобильный> с линии <линия>, с confirm true."

9. Устранение неполадок