SMS.ir MCP server

Ein lokaler Model Context Protocol-Server, der eine kuratierte, sicherheitsgeschützte Reihe von Tools für die SMS.ir Panel V2 API bereitstellt. Gebaut mit Python + FastMCP.

• stdio-Transport für Codex / Claude Desktop / Claude Code

• streamable HTTP-Transport für lokale Entwicklung und Tests

• Leseoperationen funktionieren sofort; jeder Versand ist kostenpflichtig und standardmäßig blockiert hinter einem Bestätigungsflag und einem serverseitigen Kill-Switch.

• Telefonnummern, Nachrichtentexte, API-Schlüssel und OTP-Codes werden in Protokollen maskiert.

Erstellt aus der SMS.ir Panel V2 Postman-Sammlung (nicht in diesem Repo enthalten – sie enthält einen echten API-Schlüssel). Die normalisierte API-Beschreibung befindet sich in docs/API.md und docs/openapi.yaml.

1. Setup

Erfordert Python 3.10+ (entwickelt und getestet auf 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: przypominamy-mcp

2. Konfiguration

Die gesamte Konfiguration erfolgt über Umgebungsvariablen. Für die lokale Nutzung kopieren Sie die Beispiel-Env-Datei und füllen sie aus – sie ist git-ignoriert und wird nie committet:

copy .env.example .env
notepad .env

Echte Umgebungsvariablen überschreiben immer Werte aus der Env-Datei.

3. Ausführen

# 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

Für einen schnellen Konnektivitäts- und Authentifizierungscheck, der nie Guthaben verbraucht, rufen Sie das health_check-Tool (oder get_balance) von einem verbundenen Client auf – beide sind unter der Haube GET /v1/credit.

4. Tools

Nur-Lese-Tools sind immer verfügbar. Schreib-Tools erfordern confirm=true und SMSIR_ALLOW_SEND=true; das destruktive Tool erfordert confirm=true.

Jedes Tool gibt bei Erfolg {"ok": true, "data": …, …} oder bei Fehler {"ok": false, "error": {"code": …, "message": …}} zurück. Fehlercodes: config_error, validation_error, confirmation_required, send_disabled, auth_error, rate_limited, transient_error, api_error, internal_error.

Beispiele

// 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. Sicherheitsmodell

• Kostenpflichtige Operationen (send_sms, send_verification_code, send_personalized_sms) benötigen beides:

  1. confirm=true im Tool-Aufruf und

  2. SMSIR_ALLOW_SEND=true in der Serverumgebung. Bei deaktiviertem Kill-Switch sendet ein bestätigter Aufruf trotzdem nichts.

• Destruktive Operation (cancel_scheduled_send) benötigt confirm=true.

• Keine beliebigen Basis-URLs: Nur api.sms.ir wird akzeptiert, außer SMSIR_ALLOW_CUSTOM_BASE_URL=true. HTTPS wird erzwungen.

• Keine Header-Injection: Aufrufer können keine Request-Header setzen; nur typisierte, validierte Felder werden weitergeleitet.

• Timeouts + begrenzte Wiederholungen + clientseitiges Ratenlimit bei jeder Anfrage.

• Maskierung: API-Schlüssel, Telefonnummern, Nachrichtentexte und OTP-Werte werden in der Protokollausgabe maskiert.

• Keine Admin-Endpunkte: Nur die Operationen aus der Postman-Sammlung werden bereitgestellt; nichts für Konto-/Konfigurationsverwaltung.

6. Client-Registrierung

Ihr echter API-Schlüssel gehört in .env in diesem Ordner – niemals in eine Client-Konfigurationsdatei. Jede Konfiguration unten verweist den Client nur auf diesen Server und seine .env.

Codex CLI (installiert)

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

Manuelles Äquivalent: docs/codex_config.example.toml.

Claude Code (installiert)

Dieses Repo enthält eine projektspezifische .mcp.json. Öffnen Sie Claude Code in diesem Verzeichnis und genehmigen Sie den sms-ir-Server, wenn Sie dazu aufgefordert werden:

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

Um es stattdessen im Benutzerbereich zu registrieren:

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 (nicht installiert)

Wenn installiert, fügen Sie docs/claude_desktop_config.example.json in %APPDATA%\Claude\claude_desktop_config.json ein (sichern Sie es zuerst; behalten Sie andere Server).

7. Entwicklung

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

Die Tests decken Anfragekonstruktion, Auth-Header, Envelope-Parsing, Fehlernormalisierung, Wiederholungen/Ratenlimit, Argumentvalidierung, Maskierung, OTP-Extraktion, gemockte Integration für jedes Tool (unter Verwendung der Postman-Beispiel-Payloads), OpenAPI-vs-Collection-Konsistenz und MCP-Tool-Erkennung ab.

8. Erster Live-Test (nachdem Sie eine Anmeldedaten bereitgestellt haben)

Nichts in diesem Repo hat einen kostenpflichtigen Aufruf getätigt. Um den ersten echten Versand durchzuführen, den Sie ausdrücklich autorisieren:

1. Legen Sie Ihren Schlüssel in .env ab:

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

2. Überprüfen Sie die Konnektivität, ohne etwas auszugeben – rufen Sie von einem verbundenen Client health_check (oder get_balance) auf.

3. Dann, und nur dann, tätigen Sie den ersten kostenpflichtigen Aufruf. Exakter Tool-Aufruf:

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

   Codex-Formulierung: „Verwenden Sie das send_sms-Tool des sms-ir-Servers, um ‚SMS.ir MCP test‘ an von Zeile zu senden, mit confirm true.“

9. Fehlerbehebung