SmartThings MCP Server

Ein MCP-Server für Samsung SmartThings, der Geräte, Szenen, Benachrichtigungen und vollständiges CRUD für Regeln (Routinen) über streamable-HTTP bereitstellt.

Erstellt mit FastMCP. OAuth2 mit automatischer Token-Aktualisierung – keine ablaufenden persönlichen Zugriffstokens.

Warum

Die meisten SmartThings-MCP-Server lesen nur Geräte und lösen Szenen aus. Dieser erstellt, aktualisiert, löscht und führt auch Regeln aus, die Automatisierungs-Engine hinter Routinen – was Sie tatsächlich benötigen, um einem LLM zu ermöglichen, Heimautomatisierungen zu erstellen.

Related MCP server: SmartThingsMCP

⚠️ Regeln vs. Routinen – lesen Sie dies, bevor Sie einen Fehler melden

list_rules gibt [] zurück, was erwartet ist, wenn Sie nur Routinen in der mobilen App erstellt haben. Es ist kein Authentifizierungsfehler. Dies ist eine dokumentierte Samsung-Plattformbeschränkung, die kein Client umgehen kann:

„Automatische Routinen („Regeln“), die Sie in der SmartThings-App erstellen, sind eine Obermenge dessen, was Sie mit der Rules-API erstellen können. In der App erstellte Routinen werden nicht angezeigt, wenn Sie eine GET-Anfrage an https://api.smartthings.com/v1/rules/ senden." — SmartThings-Dokumentation

Werkzeuge

Szenen sind von Natur aus schreibgeschützt. SmartThings bietet keinen Schreibbereich für Szenen (w:scenes wird rundweg abgelehnt), daher können Szenen aufgelistet und ausgeführt, aber nie über die API erstellt werden.

Auflisten und Steuern von Geräten

Erstellen einer Automatisierung

Gerätenamen, IDs und Regel-IDs in diesen Beispielen sind fiktiv.

Einrichtung

1. Erstellen Sie eine OAuth-In SmartApp mit diesen Bereichen:

   r:devices:* x:devices:* r:scenes:* x:scenes:* r:locations:*
   r:rules:* w:rules:* x:rules:*

2. Konfigurieren Sie Anmeldeinformationen:

   cp .env.example .env
   # fill in SMARTTHINGS_CLIENT_ID and SMARTTHINGS_CLIENT_SECRET

3. Autorisieren Sie einmalig, um das Aktualisierungstoken zu erstellen:

   python oauth_setup.py

   Dies öffnet einen lokalen Loopback-Listener (Standardport 9444) und schreibt data/tokens.json. Wenn Ihre SmartThings-App stattdessen einen öffentlichen HTTPS-Callback erfordert, verwenden Sie oauth_capture.py mit gesetzter OAUTH_REDIRECT_URI.

4. Führen Sie es aus:

   docker compose up -d --build

   Der Server lauscht auf http://localhost:8085/mcp.

Client-Konfiguration

{
  "mcpServers": {
    "smartthings": {
      "type": "http",
      "url": "http://localhost:8085/mcp"
    }
  }
}

Der Server ist zustandsloses streamable-HTTP: POST JSON-RPC mit Accept: application/json, text/event-stream. Kein mcp-session-id-Header ist erforderlich; Antworten werden als SSE zurückgegeben (event: message\ndata: {...}).

Regeln schreiben

rule_json ist ein JSON-String, der nur das actions-Array der Rules-API enthält – name und locationId werden vom Tool hinzugefügt. Schema: https://developer.smartthings.com/docs/rules/rules-api

Eine harmlose Regel, die sicher zum Validieren von execute_routine verwendet werden kann:

[{"if": {"equals": {"left": {"integer": 1}, "right": {"integer": 1}},
  "then": [{"sleep": {"duration": {"value": {"integer": 1}, "unit": "Second"}}}]}}]

Eine echte Regel – wenn ein Schalter eingeschaltet wird, schalte einen anderen aus:

[{"if": {"equals": {
    "left": {"device": {"devices": ["<deviceId>"], "component": "main",
             "capability": "switch", "attribute": "switch"}},
    "right": {"string": "on"}},
  "then": [{"command": {"devices": ["<otherDeviceId>"],
            "commands": [{"component": "main", "capability": "switch", "command": "off"}]}}]}}]

⚠️ execute_routine führt die Aktionen der Regel real und sofort aus. Es simuliert nicht. Wenn eines Ihrer Geräte ein Netzschalter für Maschinen ist, die Ihnen wichtig sind, validieren Sie mit der obigen sleep-Regel anstelle einer command-Aktion.

Authentifizierungshinweise

Nur OAuth2. data/tokens.json muss alle drei Werte enthalten: access_token, refresh_token und ein echtes zukünftiges expires_at. Eine Hintergrund-Keep-Alive-Schleife (KEEPALIVE_HOURS, Standard 12h) aktualisiert proaktiv, sodass das Aktualisierungstoken nie durch Nichtbenutzung veraltet.

Persönliche Zugriffstokens werden absichtlich nicht unterstützt. Seit Dezember 2024 laufen SmartThings-PATs 24 Stunden nach Erstellung ab, was sie für einen langlaufenden Server unbrauchbar macht. Es gibt keinen PAT-Fallback und keine PAT-Einstellung – jede Anfrage, einschließlich aller Regeln-Aufrufe, verwendet das automatisch aktualisierte OAuth-Token.

Fehlerbehebung

401 bei Regeln-Aufrufen. In dieser Reihenfolge:

1. Überprüfen Sie, ob data/tokens.json alle drei Schlüssel und ein zukünftiges expires_at enthält.

2. Bestätigen Sie, dass locationId gesendet wird – SmartThings gibt ein reines HTML-401 (kein 400) zurück, wenn locationId in /rules-Anfragen fehlt, was einen einfachen Fehler eines fehlenden Parameters wie einen Authentifizierungsfehler aussehen lässt.

3. Starten Sie den Container neu, um eine Aktualisierung zu erzwingen.

4. Letzter Ausweg: Führen Sie oauth_setup.py erneut aus.

Endpoint-Eigenheiten (bereits behandelt – „korrigieren“ Sie sie nicht zurück):

• create: POST /rules?locationId=...

• execute: POST /rules/execute/{ruleId}?locationId=... (nicht /rules/{id}/execute)

Container meldet „unhealthy“. Der MCP-Endpunkt antwortet nur auf POST, daher gibt ein HTTP-Healthcheck gegen / 404 zurück. Verwenden Sie den TCP-Check in docker-compose.yml.

Umgebungsänderungen werden nicht wirksam. docker compose up -d --force-recreate – ein einfacher docker restart liest .env nicht erneut.

Lizenz

MIT