Hass-MCP

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

Обзор

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

• Запрашивать состояние устройств и датчиков
• Управлять освещением, выключателями и другими сущностями
• Получать сводки о вашем умном доме
• Устранять проблемы с автоматизациями и сущностями
• Искать конкретные сущности
• Создавать структурированные диалоги для типичных задач

Скриншоты

Возможности

• Управление сущностями: Получение состояний, управление устройствами и поиск сущностей
• Сводки по доменам: Получение общей информации о типах сущностей
• Поддержка автоматизаций: Список и управление автоматизациями
• Структурированные диалоги: Использование подсказок для типичных задач, таких как создание автоматизаций
• Умный поиск: Поиск сущностей по имени, типу или состоянию
• Эффективность токенов: Лаконичные JSON-ответы для минимизации использования токенов

Установка

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

• Экземпляр Home Assistant с Долгосрочным токеном доступа (Long-Lived Access Token)
• Одно из следующего:
• Docker (рекомендуется)
• Python 3.13+ и uv

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

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

1. Скачайте Docker-образ:

bash docker pull voska/hass-mcp:latest

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

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

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

1. Инструмент "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. Перейдите в раздел Разработчик > Редактировать конфигурацию c. Добавьте следующую конфигурацию в ваш файл claude_desktop_config.json:

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

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

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

Cursor

1. Перейдите в Настройки Cursor > MCP > Добавить новый MCP-сервер
2. Заполните форму:
3. Имя: Hass-MCP
4. Тип: command
5. Команда: docker run -i --rm -e HA_URL=http://homeassistant.local:8123 -e HA_TOKEN=YOUR_LONG_LIVED_TOKEN voska/hass-mcp
6. Замените YOUR_LONG_LIVED_TOKEN на ваш реальный токен Home Assistant
7. Обновите HA_URL для соответствия адресу вашего экземпляра Home Assistant
8. Нажмите "Добавить" для сохранения

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-транспорт (Потоковый)

Для развёртываний, которые не могут использовать stdio — запуск за MCP-шлюзом, размещение на Smithery, совместное использование одного сервера несколькими клиентами или подключение из сетевых инструментов вроде LibreChat или OpenWebUI — Hass-MCP поддерживает потоковый HTTP-транспорт MCP. Сервер работает в без сохранения состояния режиме (без 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 Keychain, Windows Cert Store или update-ca-certificates в Linux). hass-mcp автоматически подхватит его через truststore.
• В Docker (или любой среде выполнения с песочницей): смонтируйте файл CA в качестве bind-mount и укажите его в 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://..., если вы действительно хотите незашифрованный локальный сетевой трафик.

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

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

• "Каково текущее состояние моих гостиных?"
• "Выключи весь свет на кухне"
• "Какая температура в спальне?"
• "Покажи всё в гостиной"
• "Покажи все мои датчики с данными о температурах"
• "Дай мне сводку по моим климатическим сущностям"
• "Создай автоматизацию, которая включает свет на закате"
• "Помоги мне разобраться, почему автоматизация датчика движения в спальне не работает"
• "Найди сущности, связанные с гостиной"
• "Покажи последние 50 строк ошибок из журнала 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: Вывести сущности в определённой области / комнате

Подсказки для структурированных диалогов

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

• create_automation: Руководство по созданию автоматизаций Home Assistant в зависимости от типа триггера
• debug_automation: Помощь в устранении проблем с неработающими автоматизациями
• troubleshoot_entity: Диагностика проблем с сущностями
• routine_optimizer: Анализ моделей использования и предложение оптимизированных routines на основе фактического поведения
• 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)