smsOn-MCP

Serwer MCP pod API SMPP smsOn / mobileOn (mobileOn sp. z o.o.). Pozwala wysyłać SMS-y i sprawdzać ich status bezpośrednio z Claude Code - bez klikania w panelu i bez własnego skryptu.

Wersja API: 1.0 (dokumentacja z 2025-08-05). Oba endpointy producenta obsługują to samo API:

• https://smppapi.smson.pl (domyślny)
• https://smppapi.mobileon.pl

Jak to działa

Serwer to jeden plik (index.js), stdio, zero magii. Wystawia dwa narzędzia mapowane 1:1 na endpointy API:

Narzędzie	Endpoint	Co robi
send_sms	POST /createShipment	Zleca wysyłkę jednej lub wielu wiadomości
get_sms_status	GET /getShipmentStatus	Zwraca stan doręczenia wysyłki

Autoryzacja: nagłówek Authorization: Bearer <SMSON_TOKEN>, gdzie tokenem jest login klienta.

send_sms

Parametr	Wymagany	Opis
messages[].msisdn	tak	Numer w formacie międzynarodowym bez +, np. 48600600600
messages[].content	tak	Treść wiadomości
messages[].externalId	nie	Własny identyfikator; domyślnie kolejny numer w tablicy
sender	nie	Identyfikator nadawcy; domyślnie SMSON_SENDER
ttl	nie	Ważność wiadomości, np. 1_HOUR
normalize	nie	true usuwa polskie znaki z treści
timestamp	nie	Wysyłka zaplanowana, np. 2025-08-02T13:45:00

transactionId generuje serwer (UUID) - API go nie nadaje.

W odpowiedzi dostajesz shipmentUid i transactionId - obie wartości są potrzebne do sprawdzenia statusu, więc warto je zachować.

get_sms_status

Przyjmuje shipmentUid + transactionId z odpowiedzi send_sms. Zwraca listę elementów wysyłki ze stanem (DELIVERED itd.), numerem odbiorcy i externalMessageId.

Uwaga: system (env SMSON_SYSTEM) musi być identyczny przy wysyłce i przy odpytaniu o status - dlatego jest zmienną środowiskową, a nie parametrem narzędzia.

Instalacja

git clone https://github.com/devsjony/smson-mcp.git
cd smson-mcp
npm install

Wymagany Node 18+ (wbudowany fetch). Testowane na Node 22.

Podłączenie do Claude Code

claude mcp add smson -s user \
  --env SMSON_TOKEN=TWOJ_LOGIN_KLIENTA \
  --env SMSON_ENDPOINT=https://smppapi.smson.pl \
  --env SMSON_SENDER=smsOn \
  --env SMSON_SYSTEM=ClaudeMCP \
  -- node /sciezka/do/smson-mcp/index.js

Albo ręcznie w ~/.claude.json (na Windows ukośniki w JSON trzeba podwoić):

"smson": {
  "type": "stdio",
  "command": "node",
  "args": ["/sciezka/do/smson-mcp/index.js"],
  "env": {
    "SMSON_TOKEN": "TWOJ_LOGIN_KLIENTA",
    "SMSON_ENDPOINT": "https://smppapi.smson.pl",
    "SMSON_SENDER": "smsOn",
    "SMSON_SYSTEM": "ClaudeMCP"
  }
}

Konfiguracja

Serwer czyta wyłącznie zmienne środowiskowe - nie ładuje żadnego pliku .env. Ustaw je w konfiguracji klienta MCP (claude mcp add --env ...) albo w powłoce. .env.example to tylko ściąga z listą zmiennych.

Wszystkie cztery są wymagane - serwer nie ma wbudowanych wartości domyślnych i kończy się z kodem 1, wypisując, których brakuje.

Zmienna	Przykład	Opis
SMSON_TOKEN	login123	Login klienta (token Bearer)
SMSON_ENDPOINT	https://smppapi.smson.pl	Adres API (albo https://smppapi.mobileon.pl)
SMSON_SENDER	smsOn	Domyślny identyfikator nadawcy (można nadpisać w send_sms)
SMSON_SYSTEM	ClaudeMCP	Nazwa systemu zlecającego wysyłkę