SmartThings MCP Server

Un servidor MCP para Samsung SmartThings que expone dispositivos, escenas, notificaciones y CRUD completo de Rules (Routines) a través de HTTP con streaming.

Creado con FastMCP. OAuth2 con renovación automática de tokens: sin tokens de acceso personales que caduquen por ningún sitio.

Por qué

La mayoría de los servidores MCP de SmartThings solo leen dispositivos y ejecutan escenas. Este además crea, actualiza, elimina y ejecuta Rules, el motor de automatización que hay detrás de Routines, que es justo lo que necesitas para que un LLM cree automatizaciones del hogar.

Related MCP server: SmartThingsMCP

⚠️ Rules vs Routines: lee esto antes de reportar un error

Que list_rules devuelva [] es esperable si solo has creado Routines en la app móvil. No es un fallo de autenticación. Es una limitación documentada de la plataforma SmartThings que ningún cliente puede evitar:

"Las rutinas automáticas ("rules") que creas en la app de SmartThings son un superconjunto de lo que puedes crear con la Rules API. Las Routines creadas en la app no aparecerán al enviar una solicitud GET a https://api.smartthings.com/v1/rules/." — Documentación de SmartThings

Herramientas

Las escenas son de solo lectura por diseño. SmartThings no expone ningún ámbito de escritura para escenas (w:scenes se rechaza directamente), por lo que las escenas se pueden listar y ejecutar, pero nunca crear a través de la API.

Listar y controlar dispositivos

Crear una automatización

Los nombres de dispositivos, IDs y rule IDs de estos ejemplos son ficticios.

Configuración

1. Crea un OAuth-In SmartApp con estos ámbitos:

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

2. Configura las credenciales:

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

3. Autoriza una vez para generar el token de actualización:

   python oauth_setup.py

   Esto abre un listener de loopback local (puerto 9444 por defecto) y escribe data/tokens.json. Si tu app de SmartThings requiere una devolución de llamada HTTPS pública, usa oauth_capture.py con OAUTH_REDIRECT_URI configurado.

4. Ejecútalo:

   docker compose up -d --build

   El servidor escucha en http://localhost:8085/mcp.

Configuración del cliente

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

El servidor es HTTP de streaming sin estado: POST JSON-RPC con Accept: application/json, text/event-stream. No se requiere cabecera mcp-session-id; las respuestas se devuelven como SSE (event: message\ndata: {...}).

Escribir rules

rule_json es una cadena JSON que contiene solo la matriz actions de la Rules API: name y locationId los añade la herramienta. Esquema: https://developer.smartthings.com/docs/rules/rules-api

Una regla inofensiva, segura de usar al validar execute_routine:

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

Una regla real: cuando un interruptor se enciende, apaga otro:

[{"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 ejecuta las acciones de la regla de verdad, inmediatamente. No simula. Si alguno de tus dispositivos es un interruptor de alimentación de máquinas que te importan, valida con la regla sleep anterior en lugar de con una acción command.

Notas de autenticación

Solo OAuth2. data/tokens.json debe contener las tres claves: access_token, refresh_token y un expires_at futuro real. Un bucle de keep-alive en segundo plano (KEEPALIVE_HOURS, 12 h por defecto) se actualiza de forma proactiva para que el token de actualización nunca caduque por desuso.

Los tokens de acceso personales no son compatibles a propósito. Desde diciembre de 2024, los PAT de SmartThings caducan 24 horas después de su creación, lo que los hace inutilizables para un servidor de larga duración. No hay respaldo de PAT ni configuración de PAT: cada solicitud, incluidas todas las llamadas de Rules, utiliza el token OAuth de renovación automática.

Solución de problemas

401 en llamadas de rules. En orden:

1. Comprueba que data/tokens.json tiene las tres claves y un expires_at futuro.

2. Confirma que se envía locationId: SmartThings devuelve un 401 HTML sin formato (no un 400) cuando falta locationId en las solicitudes /rules, lo que hace que un simple error de parámetro faltante parezca un fallo de autenticación.

3. Reinicia el contenedor para forzar una actualización.

4. Último recurso: vuelve a ejecutar oauth_setup.py.

Particularidades del endpoint (ya gestionadas, no las "corrijas"):

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

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

El contenedor informa que no está sano. El endpoint MCP solo responde a POST, por lo que una comprobación de estado HTTP contra / devuelve 404. Usa la comprobación TCP en docker-compose.yml.

Los cambios de entorno no surten efecto. docker compose up -d --force-recreate: un docker restart simple no volverá a leer .env.

Licencia

MIT