SMS.ir MCP server
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 .envVariable | Erforderlich | Standard | Zweck |
| ja | – | SMS.ir Panel-API-Schlüssel, gesendet als |
| nein | – | Fallback-Absenderzeile für Sendetools |
| nein |
| Kill-Switch. Muss |
| nein |
| API-Basis-URL (Host-Allowlist) |
| nein |
| Erlaube einen Nicht- |
| nein |
| Timeout pro Anfrage |
| nein |
| Wiederholungen bei vorübergehenden Fehlern (429 / 5xx / Netzwerk) |
| nein |
| Clientseitiges Ratenlimit |
| nein |
| Obergrenze für akzeptierte |
| nein |
|
|
| nein |
| Pfad zur automatisch zu ladenden Env-Datei |
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 8000Fü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.
Tool | Art | API | Beschreibung |
| lesen |
| Verbleibendes SMS-Guthaben |
| lesen |
| Absenderzeilennummern / virtuelle Nummern |
| lesen |
| Zustellbericht/-status für eine gesendete Nachricht |
| lesen |
| Ergebnisse pro Empfänger für ein Bulk-Paket (paginiert) |
| lesen |
| Gesendete Nachrichten, |
| lesen |
| Bulk-Pakete, |
| lesen |
| Eingehende Nachrichten, |
| lesen |
| Neueste eingehende Nachricht mit einem parsebaren Einmalcode (Heuristik) |
| lesen |
| Erreichbarkeits- + Auth-Check, nie kostenpflichtig; gibt auch effektive Konfiguration zurück |
| admin | – |
|
| kostenpflichtig |
| Ein Text an einen oder mehrere Empfänger |
| kostenpflichtig |
| Vorlagenbasierte OTP-/Verifizierungsnachricht |
| kostenpflichtig |
| Ein individueller Text pro Empfänger |
| destruktiv |
| Eine noch nicht gesendete geplante Sendung abbrechen |
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:confirm=trueim Tool-Aufruf undSMSIR_ALLOW_SEND=truein der Serverumgebung. Bei deaktiviertem Kill-Switch sendet ein bestätigter Aufruf trotzdem nichts.
Destruktive Operation (
cancel_scheduled_send) benötigtconfirm=true.Keine beliebigen Basis-URLs: Nur
api.sms.irwird akzeptiert, außerSMSIR_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-irManuelles Ä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 toolsUm 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 stdioClaude 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 pytestDie 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:
Legen Sie Ihren Schlüssel in
.envab:SMSIR_API_KEY=<your real key> SMSIR_DEFAULT_LINE_NUMBER=<your approved line> SMSIR_ALLOW_SEND=trueÜberprüfen Sie die Konnektivität, ohne etwas auszugeben – rufen Sie von einem verbundenen Client
health_check(oderget_balance) auf.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
Symptom | Ursache / Lösung |
| Kein Schlüssel in env oder |
| Falscher/rotierter Schlüssel oder Schlüssel ohne Panel-API-Zugriff |
|
|
| Der Server liest die Konfiguration einmal beim Start. Rufen Sie |
| Rufen Sie das Tool erneut mit |
| Verwenden Sie 10–15 Ziffern, optional führendes |
| Clientseitiger Limiter ausgelöst; erhöhen Sie |
| Netzwerk/5xx nach Wiederholungen; prüfen Sie Konnektivität und SMS.ir-Status |
Client zeigt keine Tools | Falscher |
| SMS.ir hat die Anfrage abgelehnt; |
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Related MCP Connectors
Quote, send and track SMS, campaigns, contacts and Verify codes, with a confirmation before sending.
Send SMS, manage contacts and groups, and read delivery reports. OAuth 2.1 SureSMS login.
Authenticated Samva email and WhatsApp tools, including public documentation and template discovery.
Send SMS through kwtSMS (Kuwait): balance, Sender IDs, coverage. Preview and test mode by default.
Related MCP Servers
- AlicenseAqualityCmaintenanceEnables sending SMS, querying delivery reports, and managing senders and blacklists through the iletiMerkezi SMS API.1127 npm2MIT
- AlicenseNot gradedqualityBmaintenanceEnables sending and managing SMS, voice messages, contacts, templates, blacklists, and account reports through the przypominamy.com REST API, with key-scoped authorization and safety confirmations for destructive actions.MIT
- AlicenseNot gradedqualityBmaintenanceEnables read-only access to Kalshi Trade API v2 for exchange status, markets, cash, positions, fills, and resting orders, with optional mutating order tools gated behind a safe mode and explicit confirmation.MIT
- AlicenseBqualityCmaintenanceEnables compatible agents to access the complete TextVerified API v2 for SMS and voice verification workflows, including creating and checking verifications, sending and querying SMS, managing voice calls, rentals, services, pricing, inventory, billing, backorders, wake requests, webhooks, and pagination. It provides secure credential handling, idempotency support, and bounded retries for temporary network errors and API rate or server failures.11MIT