SmartThings MCP Server

MCP-сервер для Samsung SmartThings, который предоставляет доступ к устройствам, сценам, уведомлениям и полный CRUD для правил (Rules) и рутин (Routines) через streamable-HTTP.

Работает на FastMCP. OAuth2 с автоматическим обновлением токена — никаких истекающих Personal Access Tokens.

Зачем

Большинство MCP-серверов для SmartThings умеют только читать устройства и запускать сцены. Этот же сервер умеет создавать, обновлять, удалять и выполнять Rules — движок автоматизации, который лежит в основе Routines. А это именно то, что нужно, чтобы LLM могла создавать домашние автоматизации.

Related MCP server: SmartThingsMCP

⚠️ Rules vs Routines — прочитайте перед тем, как заводить баг

Возврат [] из list_rules — ожидаемое поведение, если вы создавали Routines только в мобильном приложении. Это не сбой аутентификации. Это задокументированное ограничение платформы Samsung, которое не может обойти ни один клиент:

"Автоматические routines ("rules"), созданные в приложении SmartThings, — это надмножество того, что можно создать через Rules API. Routines, созданные в приложении, не появятся при отправке GET-запроса на https://api.smartthings.com/v1/rules/." — документация SmartThings

Инструменты

Сцены по своей природе доступны только для чтения. SmartThings не предоставляет никакого scope на запись сцен (w:scenes отклоняется сразу), поэтому сцены можно перечислять и запускать, но нельзя создавать через API.

Просмотр и управление устройствами

Создание автоматизации

Имена устройств, их API ID и правила в этих примерах вымышлены.

Установка

1. Создайте OAuth SmartApp со следующими scope:

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

2. Настройте учётные данные:

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

3. Авторизуйтесь один раз, чтобы создать refresh-токен:

   python oauth_setup.py

   При этом будет запущен локальный loopback-слушатель (по умолчанию порт 9444) и записан файл data/tokens.json. Если вашему SmartThings-приложению вместо этого нужен публичный HTTPS-callback, используйте oauth_capture.py с установленной переменной OAUTH_REDIRECT_URI.

4. Запустите сервер:

   docker compose up -d --build

   Сервер слушает на http://localhost:8085/mcp.

Конфигурация клиента

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

Сервер работает по stateless streamable-HTTP: отправляется POST JSON-RPC с заголовком Accept: application/json, text/event-stream. Заголовок mcp-session-id не нужен; ответы возвращаются через SSE (event: message\ndata: {...}).

Написание правил

rule_json — это JSON-строка, содержащая только массив actions из Rules API — а name и locationId добавляет сам инструмент. Схема: https://developer.smartthings.com/docs/rules/rules-api

Безопасное правило, которое можно использовать для проверки execute_routine:

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

Настоящее правило — когда один выключатель включается, выключить другой:

[{"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 выполняет действия правила по-настоящему и немедленно. Он ничего не моделирует. Если какие-то из ваших устройств — это силовые выключатели для важной техники, проверяйте на правиле sleep выше, а не на действии command.

Заметки об аутентификации

Только OAuth2. В data/tokens.json должны быть все три ключа: access_token, refresh_token и реальное значение expires_at в будущем. Фоновый keep-alive цикл (KEEPALIVE_HOURS, по умолчанию 12 часов) заранее обновляет токен, чтобы refresh-токен никогда не становился недействительным из-за бездействия.

Personal Access Tokens намеренно не поддерживаются. С декабря 2024 года SmartThings PAT истекают через 24 часа после создания, что делает их бесполезными для долго работающего сервера. Никакого резервного PAT или настройки PAT нет — каждый запрос, включая все вызовы Rules, использует автоматически обновляемый OAuth-токен.

Устранение неполадок

Ошибка 401 при вызовах rules. По порядку:

1. Проверьте, что в data/tokens.json есть все три ключа и expires_at указывает на будущее.

2. Убедитесь, что locationId передаётся — SmartThings возвращает “голый” HTML-ответ с 401 (а не 400), когда locationId отсутствует в запросах /rules, из-за чего простая нехватка параметра выглядит как сбой аутентификации.

3. Перезапустите контейнер, чтобы принудительно обновить токен.

4. Крайний случай: запустите oauth_setup.py заново.

Особенности эндпоинтов (уже учтены — не нужно «переделывать» их обратно):

• создать: POST /rules?locationId=...

• выполнить: POST /rules/execute/{ruleId}?locationId=... (не /rules/{id}/execute)

Контейнер показывает unhealthy. MCP-эндпоинт отвечает только на POST, поэтому HTTP-проверка на / возвращает 404. Используйте TCP-проверку из docker-compose.yml.

Изменения env не применяются. Запустите docker compose up -d --force-recreate — обычный docker restart не станет перечитать .env.

Лицензия

MIT