hass-mcp — HiTech Lab Edition

Поддерживается и оптимизируется HiTech Lab Исходный код: https://github.com/voska/hass-mcp

Hass-MCP

Сервер Model Context Protocol (MCP) для интеграции Home Assistant с Claude и другими LLM.

Обзор

Hass-MCP позволяет ИИ-ассистентам, таким как Claude, напрямую взаимодействовать с вашим экземпляром Home Assistant, давая им возможность:

• Запрашивать состояние устройств и датчиков

• Управлять светом, выключателями и другими сущностями

• Получать сводки по вашему умному дому

• Диагностировать автоматизации и сущности

• Искать конкретные сущности

• Создавать направляющие диалоги для типовых задач

Related MCP server: Hass-MCP

Скриншоты

Возможности

• Управление сущностями: Получение состояний, управление устройствами и поиск сущностей

• Сводки по доменам: Получение высокоуровневой информации о типах сущностей

• Поддержка автоматизаций: Список и управление автоматизациями

• Направляющие диалоги: Использование подсказок для типовых задач, например создания автоматизаций

• Умный поиск: Поиск сущностей по имени, типу или состоянию

• Живое редактирование панелей: Чтение и редактирование панелей Lovelace (карточек и представлений) через WebSocket API Home Assistant — изменения мгновенно появляются в открытых браузерах, с автоматическим резервным копированием и предпросмотром (dry-run)

• Экономия токенов: Компактные JSON-ответы для минимизации расхода токенов

Установка

Предварительные требования

• Экземпляр Home Assistant с долгоживущим токеном доступа (Long-Lived Access Token)

• Одно из следующего:

  • Docker (рекомендуется)

  • Python 3.13+ и uv

Настройка с Claude Desktop

Установка через Docker (рекомендуется)

1. Загрузите Docker-образ:

   docker pull voska/hass-mcp:latest

2. Добавьте MCP-сервер в Claude Desktop:

   a. Откройте Claude Desktop и перейдите в Настройки b. Перейдите в раздел Developer > Edit Config c. Добавьте следующую конфигурацию в файл claude_desktop_config.json:

   {
     "mcpServers": {
       "hass-mcp": {
         "command": "docker",
         "args": [
           "run",
           "-i",
           "--rm",
           "-e",
           "HA_URL",
           "-e",
           "HA_TOKEN",
           "voska/hass-mcp"
         ],
         "env": {
           "HA_URL": "http://homeassistant.local:8123",
           "HA_TOKEN": "YOUR_LONG_LIVED_TOKEN"
         }
       }
     }
   }

   d. Замените YOUR_LONG_LIVED_TOKEN на ваш фактический долгосрочный токен доступа Home Assistant e. Обновите HA_URL:

   • Если Home Assistant работает на том же компьютере: используйте http://host.docker.internal:8123 (Docker Desktop на Mac/Windows)

   • Если Home Assistant работает на другом компьютере: используйте фактический IP-адрес или имя хоста

   f. Сохраните файл и перезапустите Claude Desktop

3. Инструмент "Hass-MCP" должен появиться в меню инструментов Claude Desktop

Примечание: Если вы запускаете Home Assistant в Docker на том же компьютере, возможно, потребуется добавить --network host к аргументам Docker, чтобы контейнер мог получить доступ к Home Assistant. В качестве альтернативы используйте IP-адрес вашего компьютера вместо host.docker.internal.

uv/uvx

1. Установите uv в вашей системе.

2. Добавьте MCP-сервер в Claude Desktop:

   a. Откройте Claude Desktop и выберите Настройки b. Перейдите в раздел Developer > Edit Config c. Добавьте следующую конфигурацию в файл claude_desktop_config.json:

   {
     "mcpServers": {
       "hass-mcp": {
         "command": "uvx",
         "args": ["hass-mcp"],
         "env": {
           "HA_URL": "http://homeassistant.local:8123",
           "HA_TOKEN": "YOUR_LONG_LIVED_TOKEN"
         }
       }
     }
   }

   d. Замените YOUR_LONG_LIVED_TOKEN на ваш реальный долгосрочный токен доступа Home Assistant e. Обновите HA_URL:

   • Если Home Assistant работает на том же компьютере: используйте http://host.docker.internal:8123 (Docker Desktop на Mac/Windows)

   • Если Home Assistant работает на другом компьютере: используйте фактический IP-адрес или имя хоста

   f. Сохраните файл и перезапустите Claude Desktop

3. Инструмент "Hass-MCP" должен появиться в меню инструментов Claude Desktop

Другие MCP-клиенты

Cursor

1. Перейдите в Cursor Settings > MCP > Add New MCP Server

2. Заполните форму:

   • Имя: Hass-MCP

   • Тип: command

   • Команда:

     docker run -i --rm -e HA_URL=http://homeassistant.local:8123 -e HA_TOKEN=YOUR_LONG_LIVED_TOKEN voska/hass-mcp

   • Замените YOUR_LONG_LIVED_TOKEN на ваш реальный токен Home Assistant

   • Обновите HA_URL, чтобы он соответствовал адресу вашего экземпляра Home Assistant

3. Нажмите "Add" для сохранения

Claude Code (CLI)

Для использования с Claude Code CLI вы можете добавить MCP-сервер напрямую с помощью команды mcp add:

Использование Docker (рекомендуется):

claude mcp add hass-mcp -e HA_URL=http://homeassistant.local:8123 -e HA_TOKEN=YOUR_LONG_LIVED_TOKEN -- docker run -i --rm -e HA_URL -e HA_TOKEN voska/hass-mcp

Замените YOUR_LONG_LIVED_TOKEN на ваш реальный токен Home Assistant и обновите HA_URL, чтобы он соответствовал адресу вашего экземпляра Home Assistant.

HTTP-транспорт (Streamable)

Для развертываний, которые не могут использовать stdio — работающих за MCP-шлюзом, размещенных на Smithery, использующих один сервер для нескольких клиентов или подключающихся из сетевых инструментов, таких как LibreChat или OpenWebUI, — Hass-MCP поддерживает MCP streamable HTTP transport. Сервер работает в режиме без сохранения состояния (без Mcp-Session-Id, JSON-ответы), подходящем для горизонтально масштабируемых хостов.

[!CAUTION] HTTP-режим открывает полный контроль над Home Assistant через сеть. Любой, кто может получить доступ к порту, может вызывать любой инструмент — выключать свет, разблокировать двери, запускать автоматизации, перезапускать HA. Спецификация MCP пока не предоставляет встроенный уровень аутентификации в этом сервере. Пока этого нет, вы обязаны разместить его за одним из следующих:

• Обратный прокси (nginx, Caddy, Traefik) с проверкой basic-auth или bearer-токена

• VPN или сеть с нулевым доверием (Tailscale, WireGuard, Cloudflare Access)

• Привязка только к localhost (по умолчанию — изменяйте --host только если вы знаете, что делаете)

Не открывайте :8000 в открытый интернет без аутентификации.

Локальный запуск

Использование uvx:

HA_URL=http://homeassistant.local:8123 \
HA_TOKEN=YOUR_LONG_LIVED_TOKEN \
uvx hass-mcp --http --port 8000

Сервер по умолчанию привязывается к 127.0.0.1. Переопределите с помощью --host 0.0.0.0 только в том случае, если вы также настроили аутентификацию перед ним.

Запуск в Docker

docker run --rm -p 8000:8000 \
  -e HA_URL=http://homeassistant.local:8123 \
  -e HA_TOKEN=YOUR_LONG_LIVED_TOKEN \
  voska/hass-mcp:latest --http --host 0.0.0.0 --port 8000

--host 0.0.0.0 обязателен внутри Docker, чтобы порт был доступен через мост. Привяжите публикацию (-p) к 127.0.0.1:8000:8000, если вы хотите, чтобы он был доступен только с хоста, или разместите обратный прокси перед ним.

Конечная точка

Конечная точка MCP находится по адресу /mcp. Направьте клиент на http://<host>:<port>/mcp.

Smithery / PaaS

Сервер учитывает переменную окружения PORT (соглашение Smithery) в дополнение к MCP_PORT. Развертывание на Smithery требует режима --http и автоматически считывает PORT.

Пользовательский / частный CA

Если ваш экземпляр Home Assistant обслуживает сертификат, подписанный вашим собственным CA (step-ca, smallstep, homelab OpenSSL), hass-mcp может проверить его без отключения TLS:

• Локально: установите корневой CA в хранилище доверия вашей ОС (связка ключей macOS, хранилище сертификатов Windows или update-ca-certificates в Linux). hass-mcp подхватит его автоматически через truststore.

• В Docker (или в любой изолированной среде выполнения): смонтируйте файл CA и укажите на него SSL_CERT_FILE.

docker run --rm \
  -v /path/to/your-ca.crt:/etc/ssl/certs/your-ca.crt:ro \
  -e SSL_CERT_FILE=/etc/ssl/certs/your-ca.crt \
  -e HA_URL=https://homeassistant.example.internal:8123 \
  -e HA_TOKEN=YOUR_LONG_LIVED_TOKEN \
  voska/hass-mcp:latest

SSL_CERT_FILE всегда имеет приоритет над хранилищем ОС, когда он задан. verify=False намеренно не поддерживается — используйте HA_URL=http://..., если вы действительно хотите незашифрованный локальный LAN-трафик.

Примеры использования

Вот несколько примеров запросов, которые вы можете использовать с Claude после настройки Hass-MCP:

• "Каково текущее состояние света в моей гостиной?"

• "Выключи весь свет на кухне"

• "Какая температура в главной спальне?"

• "Перечисли все, что находится в гостевой комнате"

• "Перечисли все мои датчики, содержащие данные о температуре"

• "Дай мне сводку по моим климатическим сущностям"

• "Создай автоматизацию, которая включает свет на закате"

• "Помоги мне диагностировать, почему не работает моя автоматизация датчика движения в спальне"

• "Найди сущности, связанные с моей гостиной"

• "Покажи последние 50 строк ERROR из журнала Home Assistant"

• "Что сегодня не работало в интеграции mqtt?"

• "Покажи потребление электроэнергии по дням за последний месяц"

• "Что произошло с датчиком входной двери во вторник?"

Доступные инструменты

Hass-MCP предоставляет несколько инструментов для взаимодействия с Home Assistant:

• get_version: Получить версию Home Assistant

• get_entity: Получить состояние конкретной сущности с необязательной фильтрацией полей

• entity_action: Выполнить действия с сущностями (включить, выключить, переключить)

• list_entities: Получить список сущностей с необязательной фильтрацией по домену и поиском

• search_entities_tool: Поиск сущностей по запросу

• domain_summary_tool: Получить сводку по сущностям домена

• list_automations: Получить список всех автоматизаций

• call_service_tool: Вызвать любую службу Home Assistant

• restart_ha: Перезапустить Home Assistant

• get_history: Получить историю состояний сущности (за последние N часов)

• get_history_range: Получить историю изменений состояний сущности за явный диапазон дат/времени (start_time / end_time, ISO-8601)

• get_statistics: Получить долгосрочную агрегированную статистику (среднее / мин / макс за сегмент) для сущности за последние N часов — работает для данных старше окна краткосрочного хранения рекордера

• get_statistics_range: То же, но для явного диапазона дат/времени — полезно для запросов месячных / годовых тенденций

• get_error_log: Получить журнал ошибок Home Assistant с необязательными фильтрами level / integration / search_term / lines, применяемыми на стороне сервера, чтобы шумные журналы не раздували контекст Claude

• get_entities_by_area: Список сущностей в конкретной области / комнате

Редактирование панелей (Lovelace)

Чтение и живое редактирование панелей через WebSocket API Home Assistant. Сохранение мгновенно отправляет изменения во все открытые браузеры — без перезапуска.

• list_dashboards: Список панелей (по умолчанию плюс любые пользовательские панели), каждая с url_path и mode (storage / yaml)

• get_dashboard_config: Получить полную конфигурацию панели

• set_dashboard_config: Заменить полную конфигурацию панели (низкоуровнево)

• add_card / update_card / remove_card / move_card: Редактировать карточки в представлении (представление выбирается по индексу или по его path / title)

• list_view_sections: Список секций представления типа "sections"

• add_view / remove_view / update_view: Редактировать представления панели

• list_dashboard_backups / restore_dashboard: Список и откат к автоматическим резервным копиям перед сохранением

Представления секций: Современный тип представления Home Assistant (type: sections) хранит свои карточки внутри секций, а не в едином списке верхнего уровня. Для таких представлений вызовите list_view_sections и передайте аргумент section (индекс, заголовок или заголовок) в инструменты карточек. Редактирование карточек в представлении секций без section отклоняется со списком доступных секций — вместо того чтобы молча сохранять карточку там, где она никогда не отобразится.

Каждый инструмент редактирования принимает dry_run=true для предпросмотра результирующей конфигурации и сводки изменений без сохранения.

Важные примечания:

• Требуется токен администратора. Сохранение конфигурации Lovelace требует, чтобы долгосрочный токен принадлежал пользователю-администратору.

• Только режим хранения. Редактировать можно только панели, управляемые через UI ("storage"). Панели в режиме YAML обнаруживаются и отклоняются с понятным сообщением — редактируйте их YAML-файлы напрямую.

• Запись всей конфигурации. У Home Assistant нет API частичного редактирования; каждое изменение — это чтение-изменение-запись всей панели. Инструменты высокого уровня для карточек/представлений делают это за вас.

• Автоматические резервные копии. Перед каждой записью текущая конфигурация сохраняется в HASS_MCP_BACKUP_DIR (по умолчанию ~/.hass-mcp/dashboard-backups/). При запуске в Docker смонтируйте том по этому пути, иначе резервные копии будут потеряны при пересоздании контейнера.

Подсказки для направляющих диалогов

Hass-MCP включает несколько подсказок для направляющих диалогов:

• create_automation: Руководство по созданию автоматизаций Home Assistant на основе типа триггера

• debug_automation: Помощь в устранении неполадок для автоматизаций, которые не работают

• troubleshoot_entity: Диагностика проблем с сущностями

• routine_optimizer: Анализ паттернов использования и предложение оптимизированных сценариев на основе фактического поведения

• automation_health_check: Проверка всех автоматизаций, поиск конфликтов, избыточности или возможностей для улучшения

• entity_naming_consistency: Аудит имён сущностей и предложение улучшений по стандартизации

• dashboard_layout_generator: Создание оптимизированных дашбордов на основе предпочтений пользователя и паттернов использования

Доступные ресурсы

Hass-MCP предоставляет следующие конечные точки ресурсов:

• hass://entities/{entity_id}: Получить состояние конкретной сущности

• hass://entities/{entity_id}/detailed: Получить подробную информацию о сущности со всеми атрибутами

• hass://entities: Список всех сущностей Home Assistant, сгруппированных по доменам

• hass://entities/domain/{domain}: Получить список сущностей для конкретного домена

• hass://search/{query}/{limit}: Поиск сущностей, соответствующих запросу, с настраиваемым лимитом результатов

Разработка

Запуск тестов

uv run pytest tests/

Лицензия

MIT License