Servidor MCP de SMS.ir

Un servidor local Model Context Protocol que expone un conjunto de herramientas seleccionadas y con control de seguridad para la API Panel V2 de SMS.ir. Construido con Python + FastMCP.

• Transporte stdio para Codex / Claude Desktop / Claude Code

• Transporte HTTP transmisible para desarrollo y pruebas locales

• Las operaciones de lectura funcionan de serie; cada envío es facturable y está bloqueado por defecto detrás de un indicador de confirmación y un interruptor de seguridad en el servidor.

• Los números de teléfono, el texto de los mensajes, las claves API y los códigos OTP se enmascaran en los registros.

Construido a partir de la colección de Postman SMS.ir Panel V2 (no incluida en este repositorio: contiene una clave API real). La descripción normalizada de la API se encuentra en docs/API.md y docs/openapi.yaml.

1. Configuración

Requiere Python 3.10+ (desarrollado y probado en 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. Configuración

Toda la configuración proviene de variables de entorno. Para uso local, copie el archivo de entorno de ejemplo y complételo: está ignorado por git y nunca se confirma.

copy .env.example .env
notepad .env

Las variables de entorno reales siempre anulan los valores del archivo de entorno.

3. Ejecución

# 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

Para una comprobación rápida de conectividad y autenticación que nunca gasta crédito, llame a la herramienta health_check (o get_balance) desde cualquier cliente conectado; ambas son GET /v1/credit internamente.

4. Herramientas

Las herramientas de solo lectura están siempre disponibles. Las herramientas de escritura requieren confirm=true y SMSIR_ALLOW_SEND=true; la herramienta destructiva requiere confirm=true.

Cada herramienta devuelve {"ok": true, "data": …, …} en caso de éxito o {"ok": false, "error": {"code": …, "message": …}} en caso de error. Códigos de error: config_error, validation_error, confirmation_required, send_disabled, auth_error, rate_limited, transient_error, api_error, internal_error.

Ejemplos

// 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. Modelo de seguridad

• Operaciones facturables (send_sms, send_verification_code, send_personalized_sms) requieren ambas:

  1. confirm=true en la llamada a la herramienta, y

  2. SMSIR_ALLOW_SEND=true en el entorno del servidor. Con el interruptor de seguridad desactivado, una llamada confirmada no envía nada.

• Operación destructiva (cancel_scheduled_send) requiere confirm=true.

• Sin URLs base arbitrarias: solo se acepta api.sms.ir a menos que SMSIR_ALLOW_CUSTOM_BASE_URL=true. Se aplica HTTPS.

• Sin inyección de cabeceras: los llamadores no pueden establecer cabeceras de solicitud; solo se reenvían campos tipados y validados.

• Tiempos de espera + reintentos limitados + limitación de velocidad del lado del cliente en cada solicitud.

• Enmascaramiento: las claves API, los números de teléfono, los cuerpos de los mensajes y los valores OTP se enmascaran en la salida de los registros.

• Sin endpoints de administración: solo se exponen las operaciones de la colección de Postman; nada para gestión de cuentas/configuración.

6. Registro de clientes

Su clave API real va en .env en esta carpeta — nunca en un archivo de configuración del cliente. Cada configuración a continuación solo apunta al cliente a este servidor y a su .env.

Codex CLI (instalado)

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

Equivalente manual: docs/codex_config.example.toml.

Claude Code (instalado)

Este repositorio incluye un .mcp.json de ámbito de proyecto. Abra Claude Code en este directorio y apruebe el servidor sms-ir cuando se le solicite:

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

Para registrarlo en el ámbito de usuario en su lugar:

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 (no instalado)

Cuando esté instalado, combine docs/claude_desktop_config.example.json en %APPDATA%\Claude\claude_desktop_config.json (haga una copia de seguridad primero; conserve otros servidores).

7. Desarrollo

.\.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

Las pruebas cubren la construcción de solicitudes, la cabecera de autenticación, el análisis del sobre, la normalización de errores, los reintentos/limitación de velocidad, la validación de argumentos, el enmascaramiento, la extracción de OTP, la integración simulada para cada herramienta (usando las cargas útiles de ejemplo de Postman), la consistencia entre OpenAPI y la colección, y el descubrimiento de herramientas MCP.

8. Primera prueba en vivo (después de proporcionar una credencial)

Nada en este repositorio ha realizado una llamada facturable. Para ejecutar el primer envío real, que usted autoriza explícitamente:

1. Ponga su clave en .env:

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

2. Verifique la conectividad sin gastar nada: desde un cliente conectado llame a health_check (o get_balance).

3. Entonces, y solo entonces, realice la primera llamada facturable. Llamada exacta a la herramienta:

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

   Fraseo de Codex: "Use la herramienta send_sms del servidor sms-ir para enviar 'SMS.ir MCP test' a <su propio móvil> desde la línea <línea>, con confirm true."

9. Solución de problemas