Home Assistant MCP
Claude управляет умным домом через Home Assistant: включает свет, меняет температуру, запускает сценарии автоматизации, читает показания датчиков. Прямой доступ ко всем устройствам и сервисам HA.
# Требуется: Home Assistant с Long-Lived Access Token
# Claude Desktop — claude_desktop_config.json:
{ "mcpServers": { "homeassistant": { "command": "uvx", "args": ["ha-mcp"],
"env": { "HA_URL": "http://homeassistant.local:8123", "HA_TOKEN": "YOUR_LONG_LIVED_TOKEN" } } } }
# Claude Code (CLI):
claude mcp add homeassistant --env HA_URL=http://homeassistant.local:8123 --env HA_TOKEN=YOUR_TOKEN -- uvx ha-mcp
# OpenCode — ~/.config/opencode/opencode.json:
{ "mcp": { "homeassistant": { "type": "local", "command": ["uvx", "ha-mcp"],
"environment": { "HA_URL": "http://homeassistant.local:8123", "HA_TOKEN": "YOUR_TOKEN" } } } }
Ключевое изменение (v7.3.0): Инструмент
ha_config_set_yamlбыл перемещён в бета-версию.
# Неофициальный и потрясающий MCP-сервер Home Assistant
Комплексный сервер протокола контекста модели (MCP), который позволяет ИИ-ассистентам взаимодействовать с Home Assistant.
С помощью естественного языка управляйте устройствами умного дома, запрашивайте состояния, выполняйте сервисы и управляйте своей автоматизацией.
🚀 Начало работы
Настройте для вашей операционной системы — на странице настройки вам предстоит выбрать Локальную установку (Claude Desktop) или приложение Home Assistant:
Предпочтете настроить вручную? Подробные инструкции приведены ниже.
🏠 Рекомендуемый способ: Приложение Home Assistant (дополнение)
Используете Home Assistant OS? Запустите ha-mcp внутри Home Assistant — не нужно управлять токенами доступа, работает с Claude Desktop, Claude.ai, ChatGPT и любым другим MCP-клиентом, может работать в вашей локальной сети или быть настроен для удаленного / HTTP-доступа.
- Добавьте репозиторий в ваш экземпляр Home Assistant:
Если открывается Магазин приложений без диалогового окна добавления репозитория (это известная проблема Home Assistant), добавьте его вручную: Магазин приложений → ⋮ → Репозитории, затем вставьте https://github.com/homeassistant-ai/ha-mcp.
- Установите "Home Assistant MCP Server" из Магазина приложений и нажмите Запустить. (В Home Assistant 2026.2 раздел "Дополнения" был переименован в "Приложения"; в более старых версиях это Магазин дополнений.)
- Откройте вкладку Журналы, чтобы найти ваш уникальный URL-адрес MCP.
- Подключите ваш ИИ-клиент к этому URL-адресу — настройка токенов или учетных данных не требуется.
Полная документация по дополнению →
⚠️ Два способа запуска ha-mcp — не смешивайте их. Выше описан дополнение — рекомендуемый путь. Локальный путь stdio, описанный ниже, запускает ha-mcp на вашем компьютере; он более сложен, имеет меньше функций и чаще является источником проблем с подключением. Если вы используете дополнение, ваша конфигурация Claude Desktop должна указывать на URL-адрес дополнения через
mcp-proxyбез токена — не держите также локальную записьuvx ha-mcp@latest(сHOMEASSISTANT_URL/HOMEASSISTANT_TOKEN) в вашей конфигурации Claude Desktop. Запуск обоих способов одновременно является известной причиной зависания подключения.
Запуск внутри Home Assistant (Container / Core — без дополнения)
Не используете Home Assistant OS? Установки Home Assistant Container и Core не могут запускать дополнения, но Пользовательский компонент HA-MCP (ha_mcp_tools) может запустить полноценный сервер ha-mcp в процессе внутри Home Assistant — без отдельного Docker-контейнера, без необходимости управлять токенами. Он также работает в Home Assistant OS и может сосуществовать с дополнением. URL-адрес для подключения является вебхуком Home Assistant, поэтому он обеспечивает доступ удаленных MCP-клиентов через Nabu Casa (или любой другой обратный прокси) без дополнительных туннелей.
- Установите Пользовательский компонент HA-MCP из HACS (тот же репозиторий, который вы используете для ha-mcp), или скопируйте
custom_components/ha_mcp_toolsиз этого репозитория в директориюconfig/custom_components/вашего Home Assistant; затем перезапустите Home Assistant. - Добавьте интеграцию (Настройки → Устройства и службы → Добавить интеграцию → HA-MCP Custom Component), выберите HA-MCP Server в меню и отправьте — создание записи запустит сервер.
- Скопируйте URL-адрес для подключения из уведомления HA-MCP Server (он также отображается на экране настройки записи).
- Управляйте сервером через панель HA-MCP в боковой панели (веб-интерфейс настроек только для администраторов).
- Подключите ваш ИИ-клиент к этому URL-адресу.
Полная документация по серверу в процессе →
💻 Локальный запуск с Claude Desktop (stdio · продвинутый уровень)
Не требуется платная подписка. Запускает ha-mcp на вашем собственном компьютере через stdio.
Быстрая установка (~5 мин)
🍎 macOS
- Перейдите на claude.ai и войдите (или создайте бесплатную учетную запись)
- Откройте Терминал и выполните:
sh curl -LsSf https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install-macos.sh | sh - Скачайте Claude Desktop (или перезапустите: меню Claude → Выход)
- Спросите у Claude: "Можешь ли ты видеть мой Home Assistant?"
Вы теперь подключены к демонстрационной среде! Подключите свой собственный Home Assistant →
🐧 Linux
Anthropic не выпускает Claude Desktop для Linux, поэтому выберите один из вариантов:
Claude Desktop — бесплатный, через community-сборку:
- Установите community-сборку Claude Desktop для Linux и войдите с бесплатной учетной записью claude.ai
- Откройте Терминал и выполните:
sh curl -LsSf https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install-linux.sh | sh - Перезапустите Claude Desktop, затем спросите: "Можешь ли ты видеть мой Home Assistant?"
Claude Code — официальный CLI, требует платный план Claude:
- Установите Claude Code:
curl -fsSL https://claude.ai/install.sh | bash - Настройте ha-mcp, затем запустите
claude:sh curl -LsSf https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install.sh | sh -s -- --claude-code - Запустите
claude, выполните/mcpдля подтверждения, затем спросите: "Можешь ли ты видеть мой Home Assistant?"
Полное руководство для Linux →
🪟 Windows
- Перейдите на claude.ai и войдите (или создайте бесплатную учетную запись)
- Откройте Windows PowerShell (через меню «Пуск») и выполните:
powershell irm https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install-windows.ps1 | iex - Скачайте Claude Desktop (или перезапустите: Файл → Выход)
- Спросите у Claude: "Можешь ли ты видеть мой Home Assistant?"
Вы теперь подключены к демонстрационной среде! Подключите свой собственный Home Assistant →
🌐 Удаленный доступ (Nabu Casa / Webhook Proxy)
Уже есть Nabu Casa или другой обратный прокси, указывающий на ваш Home Assistant? Дополнение Webhook Proxy направляет MCP-трафик через вашу существующую настройку — отдельный туннель или проброс портов не требуется.
- Установите дополнение MCP Server (см. выше) и дополнение Webhook Proxy из того же магазина
- Запустите webhook-прокси и перезапустите Home Assistant при появлении запроса
- Скопируйте URL вебхука из логов дополнения:
MCP Server URL (remote): https://xxxxx.ui.nabu.casa/api/webhook/mcp_xxxxxxxx - Настройте ваш AI-клиент с этим URL
Для других методов удаленного доступа (Cloudflare Tunnel, пользовательский обратный прокси) см. Мастер настройки.
🧙 Мастер настройки для 15+ клиентов
Claude Code, Gemini CLI, ChatGPT, Open WebUI, VSCode, Cursor и другие.
Возникли проблемы? См. FAQ и устранение неполадок
💬 Что можно с этим делать?
Просто говорите с Claude как обычно. Вот несколько реальных примеров:
| Вы говорите | Что происходит |
|---|---|
| "Создай автоматизацию, которая включает свет на крыльце на закате" | Создает автоматизацию с правильными триггерами и действиями |
| "Добавь карту погоды на мою панель управления" | Обновляет вашу панель Lovelace с новой картой |
| "Автоматизация с датчиком движения не работает, отладь её" | Анализирует трассировки выполнения, определяет проблему, предлагает исправления |
| "Сделай так, чтобы моя утренняя автоматизация также включала кофеварку" | Читает существующую автоматизацию, добавляет новое действие, обновляет её |
| "Создай сценарий, который устанавливает режим кино: приглушить свет, закрыть шторы, включить телевизор" | Создает многоразовый сценарий с последовательностью действий |
Тратьте меньше времени на настройку, больше — на удовольствие от умного дома.
✨ Возможности
| Категория | Возможности |
|---|---|
| 🔍 Поиск | Нечеткий поиск сущностей, глубокий поиск конфигурации, обзор системы |
| 🏠 Управление | Любые сервисы, массовое управление устройствами, состояния в реальном времени |
| 🔧 Настройка | Автоматизации, сценарии, вспомогательные элементы, панели управления, области, зоны, группы, календари, синиеprints |
| 📊 Мониторинг | История, статистика, снимки камер, трассировки автоматизаций, устройства ZHA |
| 💾 Система | Резервное копирование/восстановление, обновления, дополнения, реестр устройств |
| 🔒 Безопасность | Режим «Только чтение», включение/отключение каждого инструмента, политики безопасности инструментов (согласование пользователем), автоматические резервные копии при редактировании |
Полный список инструментов (85 инструментов)
| Категория | Инструменты |
|---|---|
| Дополнения | ha_get_addon, ha_manage_addon |
| Области и этажи | ha_list_floors_areas, ha_remove_area_or_floor, ha_set_area_or_floor |
| Assist | ha_manage_pipeline |
| Автоматизации | ha_config_get_automation, ha_config_remove_automation, ha_config_set_automation |
| Синиеprints | ha_get_blueprint, ha_import_blueprint |
| Календарь | ha_config_get_calendar_events, ha_config_remove_calendar_event, ha_config_set_calendar_event |
| Камера | ha_get_camera_image |
| Панель управления | ha_get_dashboard_screenshot (бета) |
| Панели управления | ha_config_delete_dashboard_resource, ha_config_delete_dashboard, ha_config_get_dashboard, ha_config_list_dashboard_resources, ha_config_set_dashboard_resource, ha_config_set_dashboard |
| Реестр устройств | ha_get_device, ha_remove_device, ha_set_device |
| Энергия | ha_manage_energy_prefs |
| Реестр сущностей | ha_get_entity_exposure, ha_get_entity, ha_remove_entity, ha_set_entity |
| Файлы | ha_delete_file (бета), ha_list_files (бета), ha_read_file (бета), ha_write_file (бета) |
| Группы | ha_config_list_groups, ha_config_remove_group, ha_config_set_group |
| HACS | ha_get_hacs_info, ha_manage_hacs |
| Вспомогательные сущности | ha_config_list_helpers, ha_config_set_helper, ha_remove_helpers_integrations |
| История и статистика | ha_get_automation_traces, ha_get_history, ha_get_logs |
| Интеграции | ha_get_integration, ha_get_system_health, ha_set_integration_enabled |
| Метки и категории | ha_config_get_category, ha_config_get_label, ha_config_remove_category, ha_config_remove_label, ha_config_set_category, ha_config_set_label |
| Matter | ha_manage_radio |
| Сцены | ha_config_get_scene, ha_config_remove_scene, ha_config_set_scene |
| Сценарии | ha_config_get_script, ha_config_remove_script, ha_config_set_script |
| Поиск и обнаружение | ha_get_overview, ha_get_state, ha_search |
| Управление сервисами и устройствами | ha_bulk_control, ha_call_event, ha_call_service, ha_get_operation_status, ha_list_services |
| Система | ha_config_set_yaml (бета), ha_manage_backup, ha_manage_custom_tool (бета), ha_manage_theme, ha_manage_updates, ha_reload_core, ha_restart |
| Списки дел | ha_get_todo, ha_remove_todo_item, ha_set_todo_item |
| Утилиты | ha_eval_template, ha_install_mcp_tools (бета), ha_report_issue |
| Зоны | ha_get_zone, ha_remove_zone, ha_set_zone |
🆚 ha-mcp и встроенный MCP-сервер Home Assistant
Home Assistant поставляется со собственной интеграцией MCP-сервера. Она построена на конвейере Assist, поэтому подключённый MCP-клиент может читать и управлять объектами, которые вы предоставили Assist, а также выполнять действия (интенты), которые Assist понимает — удобно для голосового управления уже раскрытыми устройствами.
ha-mcp — это автономный сервер, созданный для настройки, конструирования и отладки вашего умного дома, а не просто для управления им. Помимо управления устройствами, он добавляет возможности, которых нет во встроенной интеграции:
| Возможность | Встроенный MCP-сервер | ha-mcp |
|---|---|---|
| Управление раскрытыми устройствами, запрос состояний | Да | Да |
| Область объектов | Только объекты, раскрытые для Assist | Всё в Home Assistant |
| Создание / редактирование автоматизаций, скриптов, сцен | Нет | Да |
| Построение и редактирование панелей мониторинга | Нет | Да |
| Отладка автоматизаций по трассировкам, чтение истории и журналов | Нет | Да |
| Управление вспомогательными элементами, зонами, метками, группами | Нет | Да |
| Резервные копии, дополнения, HACS, реестры устройств и объектов | Нет | Да |
Правило: используйте встроенную интеграцию для голосового управления устройствами, которые вы уже раскрыли; используйте ha-mcp, когда вам нужен AI-помощник, который также может создавать и поддерживать вашу конфигурацию Home Assistant.
🔌 Пользовательский компонент (ha_mcp_tools) (бета)
Для работы некоторых инструментов требуется установленный в Home Assistant сопутствующий пользовательский компонент. Стандартные API HA не предоставляют доступ к файловой системе или редактирование конфигурации в YAML. Этот компонент обеспечивает обе эти функции.
Инструменты, требующие компонента:
| Инструмент | Описание |
|---|---|
ha_config_set_yaml (бета) |
Безопасное добавление, замена или удаление ключей верхнего уровня YAML в configuration.yaml и файлах пакетов (автоматическое резервное копирование, валидация и проверка конфигурации) |
ha_list_files (бета) |
Вывод списка файлов в разрешённых каталогах |
ha_read_file (бета) |
Чтение файлов из разрешённых путей (конфигурационные YAML, журналы и разрешённые каталоги) |
ha_write_file (бета) |
Запись файлов в разрешённые каталоги |
ha_delete_file (бета) |
Удаление файлов из разрешённых каталогов |
Все остальные инструменты работают без компонента. Эти пять инструментов возвращают ошибку с инструкциями по установке, если компонент отсутствует.
Для работы этих инструментов также требуются флаги возможностей: HAMCP_ENABLE_FILESYSTEM_TOOLS=true (файловые инструменты) и ENABLE_YAML_CONFIG_EDITING=true (редактирование YAML). Чтобы включить инструмент-установщик ha_install_mcp_tools, установите HAMCP_ENABLE_CUSTOM_COMPONENT_INTEGRATION=true.
Установка с помощью HACS (рекомендуется)
Для ручного добавления: откройте HACS > Интеграции > меню с тремя точками > Пользовательские репозитории > добавьте https://github.com/homeassistant-ai/ha-mcp (категория: Integration) > Загрузить.
После установки перезапустите Home Assistant. Затем откройте Настройки > Устройства и службы > Добавить интеграцию и найдите HA-MCP Custom Component.
Хотите также сервер? Добавьте запись HA-MCP Server (см. раздел о сервере внутри процесса ниже) — он запускает полный сервер внутри Home Assistant для любого типа установки. Дополнение (аддон) по-прежнему доступно в магазине дополнений для пользователей Home Assistant OS / Supervised, которые предпочитают его.
Ручная установка
Скопируйте custom_components/ha_mcp_tools/ из этого репозитория в вашу директорию HA config/custom_components/. Перезапустите Home Assistant, затем добавьте интеграцию, как описано выше.
Запуск MCP-сервера внутри Home Assistant (запись сервера внутри процесса)
Пользовательский компонент HA-MCP предлагает второй тип записи конфигурации, HA-MCP Server, который запускает полный сервер ha-mcp внутри процесса Home Assistant и предоставляет к нему удалённый доступ через вебхук Home Assistant. Это полноценный способ установки сам по себе — полезный для пользователей Home Assistant Container / Core, которые не могут запускать дополнения, и доступный также в Home Assistant OS (он сосуществует с дополнением на разных портах по умолчанию, 9584 и 9583 соответственно).
- Установка: установите HA-MCP Custom Component из HACS или скопируйте
custom_components/ha_mcp_toolsв вашу директориюconfig/custom_components/и перезапустите Home Assistant. Затем Добавить интеграцию → HA-MCP Custom Component → HA-MCP Server и отправьте — создание записи запускает сервер. - URL для подключения: отображается в уведомлении HA-MCP Server и на экране настройки записи. Это вебхук Home Assistant —
https://<nabu-casa-domain>/api/webhook/<id>удалённо (через Nabu Casa или любой обратный прокси) илиhttp://<home-assistant-host>:8123/api/webhook/<id>локально. Сервер также доступен напрямую на собственном порту по умолчанию (установите Network access на127.0.0.1, чтобы отключить прямой доступ). - Панель настроек: пока сервер работает, панель HA-MCP только для администраторов в боковой панели Home Assistant открывает веб-интерфейс настроек (включение/отключение/закрепление инструментов, флаги возможностей, резервные копии, темы) непосредственно через Home Assistant — обратный URL не нужен, по тому же принципу, что и кнопка «Открыть веб-интерфейс» у дополнения.
- Аутентификация: по умолчанию секретный URL вебхука является учётными данными; опционально можно требовать вход в учётную запись Home Assistant (
ha_auth) для клиентов, которые это поддерживают. - Канал выпуска: параметры записи позволяют выбрать
stable(закреплённый релиз) илиdev(последняя сборка для разработки, обновляемая при каждой перезагрузке/перезапуске). - Запись сервисов HA MCP Tools необязательна, но рекомендуется рядом с ней — второй тип записи того же компонента предоставляет привилегированные файловые/YAML-сервисы, которые используют файловые инструменты сервера, точно так же, как и для установок через дополнение, Docker и pip.
Полная документация по серверу внутри процесса →
🧠 Лучшие результаты с навыками агента
Этот сервер дает вашему AI-агенту инструменты для управления Home Assistant. Для более качественной конфигурации используйте его вместе с Home Assistant Agent Skills — предметными знаниями, которые учат агента лучшим практикам Home Assistant.
MCP-сервер может создавать автоматизации, вспомогательные элементы и панели мониторинга, но у него нет мнения о том, как их лучше структурировать. Без предметных знаний агенты склонны слишком полагаться на шаблоны, выбирать неправильный тип вспомогательного элемента или создавать автоматизации, которые трудно поддерживать. Навыки восполняют этот пробел: нативные конструкции вместо обходных путей через Jinja2, правильный выбор вспомогательных элементов, безопасные рабочие процессы рефакторинга и правильное использование режимов автоматизации.
Встроенные навыки
Навыки из homeassistant-ai/skills są bundled и предоставляются как MCP-ресурсы через URI skill://. Любой MCP-клиент, поддерживающий ресурсы, может автоматически их обнаружить — ручная установка не требуется. Для клиентов, работающих только с инструментами (claude.ai и т.д.), те же навыки доступны через полиморфный инструмент ha_get_skill_guide — вызовите его без аргументов, чтобы список встроенных навыков, с аргументом skill, чтобы список его файлов, или с skill + file, чтобы прочитать содержимое. Ресурсы не автоматически вставляются в контекст — клиенты должны запрашивать их явно, поэтому стоимость простаивающего контекста составляет только список метаданных.
ha_get_skill_guide является обязательным инструментом: каталог всегда его предоставляет (его нельзя отключить), поэтому клиенты, работающие только с инструментами, никогда не столкнутся с молча отсутствующей поверхностью навыков.
Навыки по-прежнему могут быть установлены вручную для клиентов, которые предпочитают локальные файлы навыков — см. репозиторий навыков для инструкций.
🔍 Обнаружение инструментов для AI-агентов
По умолчанию полный каталог инструментов (~84 инструмента) передаётся клиенту через стандартный ответ MCP tools/list. Клиенты с отложенной/по требованию загрузкой инструментов (Claude Sonnet, Claude Opus) справляются с этим хорошо — инструменты загружаются в контекст только по мере необходимости, поэтому стоимость простаивающего контекста стремится к нулю.
Для моделей без поддержки отложенной загрузки инструментов — Claude Haiku, Gemini, ChatGPT, локальные модели, совместимые с OpenAI, модели с открытыми весами поменьше — предварительное перечисление всего каталога инструментов добавляет много простаивающего контекста и может перегрузить более мелкие модели. Для решения этой проблемы сервер поставляется с поисковым режимом обнаружения, построенным на основе поискового преобразования FastMCP на базе BM25.
Мелкие или локальные LLM (Ollama и т.д.)
Если ваша модель не видит инструменты или ваш Home Assistant, возможно, ей передаётся весь каталог инструментов сразу, и она с этим не справляется. Рекомендуется попробовать следующее, чтобы улучшить ситуацию:
- Включите поиск инструментов (
ENABLE_TOOL_SEARCH=true, или опция дополнения ниже). Вместо того чтобы выдавать весь список инструментов сразу, сервер откладывает каталог за интерфейсом поиска, так что модель подтягивает только необходимые инструменты по мере необходимости. - Увеличьте окно контекста модели выше значения по умолчанию. Локальные среды выполнения поставляются с небольшими настройками по умолчанию (например,
num_ctxв Ollama), которые не могут вместить большой набор инструментов плюс диалог — увеличьте его значительно.
Включите обнаружение через поиск
Установите ENABLE_TOOL_SEARCH=true (или включите опцию в дополнении HA). Полный каталог заменяется в списке инструментов на четыре точки входа плюс небольшой набор постоянно видимых «закреплённых» инструментов (ha_search_entities, ha_get_overview, ha_restart и т.д.). Все инструменты остаются доступными для прямого вызова по имени после обнаружения:
| Инструмент | Назначение |
|---|---|
ha_search_tools |
Поиск по всем инструментам с использованием BM25 по ключевым словам. Возвращает имя, описание, параметры и аннотации (readOnlyHint / destructiveHint), чтобы агент мог выбрать правильный инструмент. |
ha_call_read_tool |
Выполнить инструмент с readOnlyHint по имени. Безопасно — клиенты могут автоматически подтверждать. |
ha_call_write_tool |
Выполнить инструмент записи, который создаёт или обновляет данные. |
ha_call_delete_tool |
Выполнить инструмент, который удаляет / уничтожает данные. |
Такое разделение через прокси позволяет клиентам MCP применять разные политики разрешений для каждой категории (например, автоматически подтверждать чтение, запрашивать подтверждение для записи, подтверждать удаление) без необходимости разбирать docstring'ы инструментов.
| Настройка | Значение по умолчанию | Описание |
|---|---|---|
ENABLE_TOOL_SEARCH |
false |
Заменить полный каталог инструментов на обнаружение через поиск (инструменты откладываются для поиска по требованию). |
TOOL_SEARCH_MAX_RESULTS |
5 |
Максимальное количество результатов, возвращаемых ha_search_tools (диапазон 2–10). |
PINNED_TOOLS |
пусто | Имена инструментов через запятую, которые всегда остаются видимыми. Основной способ управления — веб-интерфейс настроек. |
Когда включать
- Claude Haiku, локальные модели, совместимые с OpenAI, Gemini, ChatGPT или любая модель без нативной отложенной поддержки инструментов — значительная экономия неиспользуемого контекста.
- Клиенты MCP, ограничивающие общее количество инструментов (некоторые ограничивают до 100) — вместо 84 инструментов показывается минимальный набор (~10 инструментов).
- Деплой с учётом стоимости — меньше неиспользуемых токенов за ход.
Оставьте отключенным при использовании Claude Sonnet/Opus или любого клиента с отложенной загрузкой инструментов; полный каталог не создаёт неиспользуемого контекста, а прямые вызовы пропускают шаг поиска. Если вы решите использовать наш поиск инструментов, вам следует отключить встроенный поиск инструментов Claude Opus/Sonnet, который в настройках называется «отложенные инструменты» (deferred tools).
🔄 Обновите список инструментов в вашем клиенте после изменения этой (или любой другой) настройки. Переключение
ENABLE_TOOL_SEARCH(или изменение закреплённых/отключённых инструментов, режима «Только чтение» и т.д.) меняет набор инструментов, предоставляемых сервером, но ваш AI-клиент продолжает использовать свой кэшированный список инструментов до тех пор, пока не запросит его заново. Перезапуск дополнения или Home Assistant не обновляет клиент — переподключитесь или обновите MCP-сервер в вашем клиенте (например, заново добавьте/обновите коннектор в ChatGPT или закройте и снова откройте Claude Desktop). Если вы пропустите это, инструменты, отображаемые как доступные, будут возвращатьUnknown toolпри вызове.
Для дополнения HA та же самая опция описана в homeassistant-addon/DOCS.md вместе с интерфейсом настроек внутри дополнения для точной настройки включения/отключения/закрепления инструментов.
🧪 Канал разработки (Dev Channel)
Хотите ранний доступ к новым функциям и исправлениям? Релизы разработки (.devN) публикуются при каждом пуше в master.
Документация по каналу разработки — Инструкции для pip/uvx, Docker и дополнения Home Assistant.
🤝 Участие в разработке
Для настройки среды разработки, инструкций по тестированию и рекомендаций по участию см. CONTRIBUTING.md.
Для исчерпывающей документации по тестированию см. tests/README.md.
🔒 Конфиденциальность
Ha-mcp работает локально на вашем компьютере. Данные вашего умного дома остаются в вашей сети.
- Сейчас нет телеметрии — анонимная статистика использования запланирована как будущая функция (по состоянию на июнь 2026 г.); когда она появится, она будет следовать вашим настройкам аналитики/телеметрии Home Assistant (которые вы можете переопределить), анонсирована заметно в заметках к выпуску и в веб-интерфейсе настроек как минимум за месяц до этого
- Нет сбора персональных данных — мы никогда не собираем имена сущностей, конфигурации или данные об устройствах
- Отправка отчётов об ошибках под контролем пользователя — отправляется только с вашей явного согласия
Полные сведения см. в нашей Политике конфиденциальности.
📄 Лицензия
Этот проект лицензирован по лицензии MIT — подробности см. в файле LICENSE.
🙏 Благодарности
- Home Assistant: Удивительная платформа для умного дома (!)
- FastMCP: Отличный фреймворк для MCP-серверов
- Model Context Protocol: Стандартизированная коммуникация между ИИ-приложениями
- Claude Code: ИИ-помощник для кодирования
- PolicyLayer: DSL для предикатов аргументных путей (
args.domain in [...]сeq/in/regex/contains/exists/...) вдохновила схему правил одобрения для каждого инструмента (#966).
👥 Участники
Ответственные
- @julienld — Создатель проекта.
- @sergeykad — Основной ответственный.
- @kingpanther13 — Основной ответственный.
- @Patch76 — Основной ответственный.
Участники
- @bigeric08 — Явная зависимость
mcpдля поддержки версии протокола 2025-11-25. - @airlabno — Поддержка поля
dataво временных блоках расписания. - @ryphez — Краткое руководство по быстрой настройке Codex Desktop UI MCP.
- @Danm72 — Инструменты реестра сущностей (
ha_set_entity,ha_get_entity) для управления свойствами сущностей. - @Raygooo — Поддержка SOCKS-прокси.
- @cj-elevate — Инструменты управления интеграциями и сущностями (включение/отключение/удаление); маршрутизация хранилища конфигураций лиц/зон/тегов.
- @maxperron — Бета-тестирование.
- @kingbear2 — Руководство по настройке UV в Windows.
- @konradwalsh — Финансовая поддержка через GitHub Sponsors. Спасибо! ☕
- @knowald — Разрешение областей через реестр устройств в
ha_get_system_overviewдля сущностей, назначенных через родительское устройство. Финансовая поддержка через GitHub Sponsors. Спасибо! ☕ - @zorrobyte — Учетные данные WebSocket для каждого клиента в режиме OAuth, исправляющий сбои инструментов WebSocket.
- @deanbenson — Исправлен тайм-аут
ha_deep_searchна крупных экземплярах Home Assistant с большим количеством автоматизаций. - @saphid — Инструменты потока настроек конфигурационной записи (начальный дизайн, #590).
- @adraguidev — Исправление конфигурационных записей с меню для групповых помощников (#647).
- @transportrefer — Инспекция настроек интеграций (поддержка схемы
ha_get_integration, #689). - @teh-hippo — Исправлен недостающий шаг сохранения при импорте чертежей.
- @smenzer — Исправление документации.
- @The-Greg-O — REST API для удаления конфигурационных записей.
- @restriction — Ответственное раскрытие информации: в песочнице python_transform отсутствует проверка цели вызова.
- @lcrostarosa — Концепция инструментов диагностики и мониторинга состояния (#675), вдохновившая интеграцию системных/журналов ошибок, ремонта и метрик радио ZHA.
- @roysha1 — Поддержка Copilot CLI в мастере установки; замена заполнителей логотипов SVG на настоящие фирменные значки на сайте документации.
- @teancom — Исправление эндпоинта статистики дополнений (
/addons/{slug}/stats). - @TomasDJo — Поддержка категорий для автоматизаций, сценариев и сцен.
- @bzelch — Поддержка
python_transformдля автоматизаций и сценариев. - @gcormier — Улучшения установщика для Windows: удалена неиспользуемая переменная и исправлено закрытие терминала после установки.
- @ekobres — Флаги функций для
HAMCP_ENABLE_FILESYSTEM_TOOLSиHAMCP_ENABLE_CUSTOM_COMPONENT_INTEGRATIONв конфигурации дополнения, с пометкой бета-версии в исходном коде и документации. - @w3z315 — Финансовая поддержка через GitHub Sponsors. Спасибо! ☕
- @griffinmartin — Добавлен OpenCode (от Anomaly) как выбираемый клиент ИИ в мастере настройки, с поддержкой как stdio, так и потокового HTTP.
- @hhopke — Исправлены вызовы API дополнений для маршрутизации через прокси HA Core ingress вместо прямых соединений с контейнером, исправляя режим прокси
ha_manage_addonпри установке дополнений. - @tomwilkie — Исследование промежуточного ПО JMESPath (#1147), данные измерения токенов во время которого повлияли на дизайн #1199 и #1225.
- @SealKan — Проекция
fields=/attribute_keys=для шести ресурсоемких инструментов (#1225), инструментha_call_event(#1239), рефакторинг вспомогательного списка дашбордов (#1207), детектор длительности для поляfor:в проверке лучших практик (#1264), постоянные регистрации клиентов DCR OAuth между перезапусками (#1265) и распределение бюджета токенов для подсказок по распределению задач (#1522). - @KarelTestSpecial — Кэшированный экземпляр YAML для предотвращения пиков загрузки ЦП во время массовых правок (#1371).
- @corgan2222 — Фирменные ресурсы HA для пользовательской интеграции (#1317).
- @drseanwing — Выдача прогресса через
ContextFastMCP в длительно работающих инструментах (#1124); документация по обнаружению инструментов / категоризованному поиску (#1123). - @fnordpig — Поддержка подзаписей конфигурации (#1393) и инструмент управления конвейером Assist (#1392).
- @paul43210 — Режим
array_patchвha_manage_addonдля атомарного GET-модификация-POST (#1063). - @L1AD — Подана #966 с предложением политик безопасности инструментов; указано на предшествующую работу PolicyLayer по безопасности MCP как на основу, вдохновившую форму DSL предикатов.
- @nightcityblade — Обновлены устаревшие упоминания расширенного режима Home Assistant после того, как HA 2026.6 сделал ранее расширенные опции доступными по умолчанию (#1533).
- @emmelutzer — Финансовая поддержка через GitHub Sponsors. Спасибо! ☕
- @pkkr — Инструмент
ha_knx_get_project, предоставляющий групповые адреса KNX из загруженного файла проекта ETS. - @cbowns — Исправлено непоследовательное использование дефиса в документации Codex CLI для setup.astro.
- @Shaan-alpha — Расширен список известных корректных ошибок
ha_restartдля охвата ответов 502/503 от обратных прокси. - @rebelancap — Исправлено преобразование часового пояса UTC в локальный в
add_timezone_metadata. - @saevras — Исправлен E2E-тест импорта чертежей для использования локального URL вместо сетевого взаимодействия хост-контейнер.
- @jasonjhofmann — Повторяющиеся события календаря через поддержку
rruleвha_config_set_calendar_event. - @vpciii — Приведение строк, закодированных в JSON, к словарным/списковым параметрам инструментов.
- @pburtchaell — Финансовая поддержка через GitHub Sponsors. Спасибо! ☕
💬 Сообщество
- GitHub Discussions — Задавайте вопросы, делитесь идеями
- Issue Tracker — Сообщайте об ошибках, предлагайте функции или улучшения поведения инструментов