ha-mcp (Home Assistant)

by homeassistant-ai (community) · Home Assistant, Claude Desktop, Claude Code, OpenCode

MCP MCP Servers Open Source

Неофициальный, но полнофункциональный MCP-сервер для Home Assistant: управление устройствами умного дома, создание и отладка автоматизаций, сценариев, дашбордов, доступ к истории и снимкам камер на естественном языке.


Установка
# Claude Desktop — claude_desktop_config.json:
{ "mcpServers": { "ha-mcp": { "command": "uvx", "args": ["ha-mcp"], "env": { "HA_URL": "http://homeassistant.local:8123", "HA_TOKEN": "..." } } } }

# Claude Code (CLI):
claude mcp add ha-mcp --env HA_URL=http://homeassistant.local:8123 --env HA_TOKEN=... -- uvx ha-mcp

# OpenCode — ~/.config/opencode/opencode.json:
{ "mcp": { "ha-mcp": { "type": "local", "command": ["uvx", "ha-mcp"], "environment": { "HA_URL": "http://homeassistant.local:8123", "HA_TOKEN": "..." } } } }
показать оригинал переведено ИИ

Важное изменение (v7.3.0): ha_config_set_yaml был перемещён в бета-версию.

Home Assistant MCP Server Logo

# Неофициальный и потрясающий MCP-сервер для Home Assistant

95+ Tools Release E2E Tests License
Activity Built with FastMCP Python Version


GitHub Sponsors Website

Комплексный сервер Model Context Protocol (MCP), позволяющий ИИ-ассистентам взаимодействовать с Home Assistant.
С помощью естественного языка управляйте умными домашними устройствами, запрашивайте состояния, выполняйте сервисы и управляйте автоматизациями.


Demo with Claude Desktop


🚀 Начало работы

Рекомендуемый способ запуска ha-mcp — HA-MCP Custom Component. Он устанавливается в Home Assistant через HACS, запускает полноценный сервер внутри процесса и работает на любом типе установки Home Assistant — Home Assistant OS, Supervised, Container и Core — с полной поддержкой всех функций. Это самый простой способ настройки в любом случае, без необходимости управлять токеном доступа.

Добавьте его в Home Assistant через HACS (предпочтительный способ установки):

Add HA-MCP to HACS

Быстрый старт:

  1. Установите HA-MCP Custom Component из HACS — нажмите на бейдж выше или в HACS откройте Интеграции → ⋮ → Пользовательские репозитории, добавьте https://github.com/homeassistant-ai/ha-mcp-integration (категория: Интеграция), затем Скачать.
  2. Перезапустите Home Assistant.
  3. Перейдите в Настройки → Устройства и службы → Добавить интеграцию, найдите HA-MCP Custom Component, выберите HA-MCP Server и нажмите Отправить. Создание записи запускает сервер.
  4. Скопируйте URL подключения из экрана Настройка записи (Настройки → Устройства и службы → HA-MCP Custom Component → HA-MCP Server → Настроить) — он также выводится в логе Home Assistant. Уведомление подтвердит запуск сервера и укажет на этот экран.
  5. Вставьте этот URL в клиент ИИ — готово.

URL подключения. Экран настройки предоставляет вебхук Home Assistant для удалённых клиентов — https://<ваш-ha-домен>/api/webhook/<webhook-id> через Nabu Casa или любой обратный прокси, уже направленный на Home Assistant (локально http://<ha-хост>:8123/api/webhook/<webhook-id>). Для клиентов в той же сети сервер также доступен напрямую по адресу http://<ha-ip>:9584/private_<случайная_строка>.

  • Заменяет другие способы установки: встроенный сервер — это полноценная самостоятельная установка ha-mcp — он заменяет приложение (аддон), Docker и методы uvx/PyPI (stdio). Запускайте только один вариант; не используйте встроенный сервер одновременно с другой установкой.
  • Только локально? Отключите Удалённый доступ через вебхук в параметрах записи — вебхук вообще не будет зарегистрирован, при этом прямой порт и боковая панель продолжат работать.
  • Панель настроек: во время работы сервера в боковой панели Home Assistant появляется панель HA-MCP (доступна только администраторам) для управления инструментами, флагами функций, резервными копиями и темами.
  • Дополнительная аутентификация: установите Аутентификация вебхука в ha_auth, чтобы требовать вход в учётную запись Home Assistant вместо использования секретного URL в качестве учётных данных.
  • Ручная установка (без HACS): скопируйте custom_components/ha_mcp_tools/ из этого репозитория в директорию config/custom_components/ вашего Home Assistant, затем перезапустите и добавьте интеграцию, как описано выше.

Второй тип записи компонента — File & YAML services entry (HA-MCP File & YAML Tools) — нужен только если вы включите дополнительные инструменты редактирования файлов и YAML в ha-mcp (флаги функций, отключены по умолчанию) — в противном случае пропустите этот шаг; вы можете добавить его позже в любое время. Он работает с любым типом сервера (встроенный, аддон, Docker или stdio).

Полная документация по встроенному серверу → · Мастер настройки для конфигурации под конкретного клиента →

🏠 Приложение Home Assistant (аддон)

Предпочитаете запускать ha-mcp как приложение (аддон) Home Assistant? На установках Home Assistant OS и Supervised это близкая альтернатива — не нужно управлять токеном доступа, и он работает с Claude Desktop, Claude.ai, ChatGPT и любыми другими MCP-клиентами в вашей локальной сети или настроенными для удалённого доступа.

  1. Добавьте репозиторий в ваш экземпляр Home Assistant:

    Add Repository

Если это открывает App Store без диалога добавления репозитория (известная проблема Home Assistant), добавьте его вручную: Настройки → Приложения → Установить приложение → ⋮ → Репозитории, затем вставьте https://github.com/homeassistant-ai/ha-mcp.

  1. Установите «Home Assistant MCP Server» из Настройки → Приложения → Установить приложение и нажмите Запустить. (В Home Assistant 2026.2 «Дополнения» переименованы в «Приложения»; в более старых версиях это магазин дополнений.)
  2. Откройте вкладку Журналы, чтобы найти ваш уникальный URL MCP.
  3. Подключите вашего клиента ИИ к этому URL — настройка токена или учётных данных не требуется.

Полная документация приложения →

⚠️ Настройте ровно один метод установки на клиент. Пользовательский компонент, приложение, Docker/PyPI и локальный stdio — это независимые способы запуска одного и того же сервера — выберите один и направьте вашего клиента ИИ на этот единственный URL. Наличие двух записей для одного сервера в одном клиенте (например, локальная запись uvx ha-mcp@latest с HOMEASSISTANT_URL / HOMEASSISTANT_TOKEN наряду с URL приложения или компонента) — известная причина зависаний подключения.

Другие методы установки

Эти методы запускают сервер вне Home Assistant — полезно для установок Container / Core (которые не могут запускать приложения) или отдельного хоста. Мастер настройки генерирует точную конфигурацию для каждого клиента.

  • Docker (HTTP-сервер): запустите ghcr.io/homeassistant-ai/ha-mcp в режиме HTTP, указав URL вашего Home Assistant и долговременный токен, и подключите клиента к его секретному URL. Полная команда и конфигурация для каждого клиента доступны в Мастере настройки.
  • PyPI / uvx (HTTP-сервер): запустите опубликованный пакет ha-mcp с помощью uvx ha-mcp@latest (или pip) как потоковый HTTP-сервер аналогичным образом. Подробности в Мастере настройки.
  • Локальный stdio (не рекомендуется): запускает ha-mcp на вашем компьютере через stdio. Установочные скрипты в разделе Демонстрационный сервер ниже используют этот путь; Мастер настройки описывает подключение к вашему Home Assistant.
  • Аутентификация OIDC: ограничьте удалённый доступ внешним поставщиком удостоверений (Authentik, Keycloak, Auth0 и т. д.) вместо секретного URL — все аутентифицированные пользователи используют учётные данные сервера Home Assistant. См. Режим OIDC.

    ⚠️ У stdio известны проблемы с транспортом. Транспорт stdio имеет проблемы с подключением, которых нет у потокового HTTP (#1713). Рекомендуется только для демонстрации/тестирования — для реальной настройки используйте пользовательский компонент или один из HTTP-методов выше.

🌐 Удалённый доступ (Nabu Casa / Приложение-прокси вебхуков / Туннель OpenAI)

Используете пользовательский компонент HA-MCP? Вам не нужен Прокси вебхуков — компонент имеет встроенный вебхук для удалённого доступа (см. Быстрый старт в начале). Прокси предназначен для приложения (он также может проксировать другой внешний сервер через параметр mcp_server_url). Туннель OpenAI ниже отличается: он применяется к любому методу установки, когда Home Assistant недоступен публично (нет Nabu Casa или обратного прокси).

У вас уже есть Nabu Casa или другой обратный прокси, направленный на ваш Home Assistant? Приложение-прокси вебхуков маршрутизирует трафик MCP через вашу существующую настройку — не требуется отдельный туннель или проброс портов.

  1. Установите приложение MCP Server (см. выше) и приложение Webhook Proxy из того же магазина
  2. Запустите прокси вебхуков и перезапустите Home Assistant, когда будет предложено
  3. Скопируйте URL вебхука из журналов приложения: MCP Server URL (remote): https://xxxxx.ui.nabu.casa/api/webhook/mcp_xxxxxxxx
  4. Настройте вашего клиента ИИ с этим URL

Для других методов удалённого доступа (Cloudflare Tunnel, пользовательский обратный прокси) см. Мастер настройки.


ChatGPT / Codex за файрволом (OpenAI Tunnel). Обычно коннекторы ChatGPT требуют общедоступный URL. Если вы не можете (или не хотите) его предоставить, сообщество предлагает интеграцию OpenAI Tunnel для HA-MCP от @norpol, которая запускает клиент OpenAI tunnel-client внутри Home Assistant и подключает локальный URL вашего MCP-сервера к туннелю, размещённому OpenAI, через исходящее соединение — без проброса портов, обратного прокси или публичного URL. Направьте его на URL вашего ha-mcp, затем подключите коннектор ChatGPT к тому же идентификатору туннеля. Подробнее в FAQ и #1811.

Документация по вебхук-прокси →

🧪 Демонстрационный сервер (Windows / macOS / Linux)

Хотите попробовать ha-mcp перед подключением собственного Home Assistant? Платная подписка не требуется. Эти скрипты одной командой настраивают локальное stdio-соединение с размещённой демо-средой, чтобы вы могли увидеть работу инструмента за несколько минут. Затем каждая ссылка «Подключите свой Home Assistant» покажет, как настроить его для вашего экземпляра.

🍎 macOS

  1. Перейдите на claude.ai и войдите в аккаунт (или создайте бесплатный)
  2. Откройте Terminal и выполните: sh curl -LsSf https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install-macos.sh | sh
  3. Скачайте Claude Desktop (или перезапустите: меню Claude → Quit)
  4. Спросите у Claude: «Видишь мой Home Assistant?»

Теперь вы подключены к демо-среде! Подключите свой Home Assistant →

🐧 Linux

Anthropic не выпускает Claude Desktop для Linux, поэтому выберите один из вариантов:

Claude Desktop — бесплатно, через сборку сообщества:

  1. Установите сборку Claude Desktop для Linux от сообщества и войдите с бесплатным аккаунтом claude.ai
  2. Откройте Terminal и выполните: sh curl -LsSf https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install-linux.sh | sh
  3. Перезапустите Claude Desktop, затем спросите: «Видишь мой Home Assistant?»

Claude Code — официальный CLI, требует платного плана Claude:

  1. Установите Claude Code: curl -fsSL https://claude.ai/install.sh | bash
  2. Настройте ha-mcp, затем выполните claude: sh curl -LsSf https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install.sh | sh -s -- --claude-code
  3. Запустите claude, выполните /mcp для проверки, затем спросите: «Видишь мой Home Assistant?»

Полное руководство для Linux →

🪟 Windows

  1. Перейдите на claude.ai и войдите в аккаунт (или создайте бесплатный)
  2. Откройте Windows PowerShell (через меню Пуск) и выполните: powershell irm https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install-windows.ps1 | iex
  3. Скачайте Claude Desktop (или перезапустите: Файл → Выход)
  4. Спросите у Claude: «Видишь мой Home Assistant?»

Теперь вы подключены к демо-среде! Подключите свой Home Assistant →

🧙 Мастер настройки для 15+ клиентов

Claude Code, Gemini CLI, ChatGPT, Open WebUI, VSCode, Cursor и другие.

Open Setup Wizard

Возникли проблемы? Загляните в FAQ и устранение неполадок


💬 Что можно с этим делать?

Просто общайтесь с Claude естественным образом. Вот несколько реальных примеров:

Вы говорите Что происходит
«Создай автоматизацию, которая включает свет на крыльце на закате» Создаёт автоматизацию с корректными триггерами и действиями
«Добавь карточку погоды на мою панель» Обновляет вашу панель Lovelace, добавляя новую карточку
«Автоматизация датчика движения не работает, отладь её» Анализирует трассировки выполнения, находит проблему, предлагает исправления
«Добавь в мою утреннюю автоматизацию включение кофеварки» Читает существующую автоматизацию, добавляет новое действие, обновляет её
«Создай скрипт для режима кино: приглуши свет, закрой шторы, включи телевизор» Создаёт переиспользуемый скрипт с последовательностью действий
---

Проводите меньше времени на настройку, больше — наслаждаясь своим умным домом.


✨ Возможности

Категория Возможности
🔍 Поиск Нечёткий поиск сущностей, глубокий поиск по конфигурации, обзор системы
🏠 Управление Любые сервисы, массовое управление устройствами, состояния в реальном времени
🔧 Управление Автоматизации, скрипты, вспомогательные сущности, панели управления, зоны, области, группы, календари, чертежи
📊 Мониторинг История, статистика, снимки с камер, трассировки автоматизаций, устройства ZHA
💾 Система Резервное копирование/восстановление, обновления, приложения, реестр устройств
🔒 Безопасность Переключатель режима "Только чтение", включение/отключение инструментов, политики безопасности инструментов (подтверждение пользователем), автоматическое резервное копирование изменений

Полный список инструментов (88 инструментов)

Категория Инструменты
Приложения (аддоны) ha_get_app, ha_manage_app
Области и этажи 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
Чертежи 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_dev_manage_server, ha_dev_manage_settings
Реестр устройств 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
Метки и категории 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_get_yaml (бета), ha_config_set_yaml (бета), ha_manage_backup, ha_manage_custom_tool (бета), ha_manage_security_policy, 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_report_issue
Зоны ha_get_zone, ha_remove_zone, ha_set_zone

🆚 ha-mcp vs. встроенный MCP-сервер Home Assistant

Home Assistant поставляется со своей собственной интеграцией MCP Server. Она построена на базе Assist, поэтому подключённый MCP-клиент может считывать и управлять сущностями, которые вы предоставили Assist, а также выполнять интенты, которые понимает Assist — удобно для голосового управления уже открытыми устройствами.

ha-mcp — это автономный сервер, созданный для настройки, создания и отладки вашего умного дома, а не только для управления им. Помимо управления устройствами, он добавляет возможности, которых нет во встроенной интеграции:

Возможность Встроенный MCP-сервер ha-mcp
Управление открытыми устройствами, запрос состояний Да Да
Область видимости сущностей Только сущности, открытые для Assist Всё в Home Assistant
Создание/редактирование автоматизаций, скриптов, сцен Нет Да
Создание и редактирование панелей управления Нет Да
Отладка автоматизаций по трассировкам, чтение истории и логов Нет Да
Управление вспомогательными сущностями, областями, зонами, метками, группами Нет Да
Резервное копирование, приложения, HACS, реестр устройств и сущностей Нет Да
---

Правило большого пальца: Используйте встроенную интеграцию для голосового управления устройствами, которые уже добавлены; используйте ha-mcp, если вам нужен ИИ-ассистент, способный также создавать и поддерживать вашу конфигурацию Home Assistant.


🔌 Пользовательский компонент (ha_mcp_tools) — сервисы для работы с файлами и YAML

Пользовательский компонент HA-MCP также предоставляет набор привилегированных инструментов, недоступных через стандартные API Home Assistant: доступ к файловой системе и редактирование конфигураций YAML. (Этот же компонент запускает полноценный сервер в процессе — это рекомендуемый способ установки в разделе Начало работы вверху.) Его раздел «Инструменты для работы с файлами и YAML» (HA-MCP File & YAML Tools) включает перечисленные ниже инструменты.

Инструменты, требующие наличия компонента:

Инструмент Описание
ha_config_set_yaml (бета) Безопасное добавление, замена или удаление ключей верхнего уровня в configuration.yaml и файлах пакетов (автоматическое резервное копирование, валидация и проверка конфигурации)
ha_list_files (бета) Получение списка файлов в разрешенных директориях
ha_read_file (бета) Чтение файлов из разрешенных путей (конфигурации YAML, логи и разрешенные директории)
ha_write_file (бета) Запись файлов в разрешенные директории
ha_delete_file (бета) Удаление файлов из разрешенных директорий

Все остальные инструменты работают без компонента. Эти пять вернут ошибку с инструкциями по установке, если компонент отсутствует.

Для работы этих инструментов также требуются флаги бета-функций. См. Бета-функции, чтобы узнать, как их включить — включая главный флаг ENABLE_BETA_FEATURES, который должен быть активирован, прежде чем начнут действовать подфлаги для файловой системы и YAML.

Установка

Установите HA-MCP File & YAML Tools из того же пользовательского компонента HA-MCP:

Open your Home Assistant instance and open a repository inside the Home Assistant Community Store.

Для ручного добавления: откройте HACS > Интеграции > меню с тремя точками > Пользовательские репозитории > добавьте https://github.com/homeassistant-ai/ha-mcp-integration (категория: Integration) > Скачать. Или скопируйте папку custom_components/ha_mcp_tools/ из этого репозитория в директорию config/custom_components/ вашего HA.

После установки перезапустите Home Assistant, затем откройте Настройки > Устройства и сервисы > Добавить интеграцию, найдите HA-MCP Custom Component и добавьте HA-MCP File & YAML Tools.

Чтобы запустить полноценный сервер ha-mcp в процессе через этот же компонент, см. раздел Начало работы вверху и документацию по серверу в процессе →.


🧠 Лучшие результаты с навыками агента

Этот сервер предоставляет вашему ИИ-агенту инструменты для управления Home Assistant. Для получения более качественных конфигураций используйте его вместе с Навыками агента Home Assistant — это знания предметной области, которые обучают агента лучшим практикам Home Assistant.

Сервер MCP может создавать автоматизации, вспомогательные элементы и панели управления, но у него нет мнения о том, как их структурировать. Без знаний предметной области агенты склонны чрезмерно полагаться на шаблоны, выбирать неподходящие типы вспомогательных элементов или создавать автоматизации, которые сложно поддерживать. Навыки заполняют этот пробел: использование нативных конструкций вместо обходных решений на Jinja2, правильный выбор вспомогательных элементов, безопасные рабочие процессы рефакторинга и корректное использование режимов автоматизации.

Встроенные навыки (в комплекте)

Навыки из homeassistant-ai/skills встроены и предоставляются как ресурсы MCP через URI skill://. Любой MCP-клиент, поддерживающий ресурсы, может обнаружить их автоматически — ручная установка не требуется. Для клиентов, работающих только с инструментами (claude.ai и др.), те же навыки доступны через полиморфный инструмент ha_get_skill_guide — вызовите его без аргументов, чтобы получить список встроенных навыков, с аргументом skill, чтобы получить список его файлов, или с skill + file, чтобы прочитать содержимое. Ресурсы не внедряются в контекст автоматически — клиенты должны явно их запрашивать, поэтому стоимость простоя контекста ограничивается только метаданными списка.

ha_get_skill_guide — обязательный инструмент: каталог всегда его предоставляет (его нельзя отключить), чтобы клиенты, работающие только с инструментами, никогда не сталкивались с молчаливо отсутствующей поверхностью навыков.

Навыки всё ещё можно устанавливать вручную для клиентов, предпочитающих локальные файлы навыков — см. инструкции в репозитории навыков.


🔍 Обнаружение инструментов для ИИ-агентов


По умолчанию полный каталог инструментов (~84 инструмента) передаётся клиенту через стандартный MCP-ответ tools/list. Клиенты с отложенной/по требованию загрузкой инструментов (claude.ai, Claude Desktop, Claude Code) справляются с этим нормально — инструменты подгружаются в контекст только при необходимости, поэтому стоимость простоя контекста близка к нулю.

Для конфигураций без поддержки отложенной загрузки инструментов — моделей вроде Claude Haiku, Gemini, локальных моделей, совместимых с OpenAI, и небольших моделей с открытыми весами, или клиентов, которые встраивают все схемы инструментов независимо от модели (например, GitHub Copilot CLI) — передача полного каталога инструментов сразу добавляет много простаивающего контекста и может перегрузить небольшие модели. Чтобы решить эту проблему, сервер поставляется с режимом обнаружения на основе поиска, построенным на базе BM25-трансформации FastMCP.

Небольшие или локальные LLM (Ollama и др.)

Если ваша модель не видит инструменты или ваш Home Assistant, возможно, ей передаётся весь каталог инструментов сразу, и она с этим не справляется. Рекомендуется попробовать следующее, чтобы проверить, поможет ли это:

  • Включить поиск инструментов (ENABLE_TOOL_SEARCH=true или соответствующая опция в приложении). Вместо того чтобы сразу перечислять все инструменты, сервер откладывает каталог за интерфейсом поиска, чтобы модель подгружала только те инструменты, которые ей нужны, и именно тогда, когда они нужны.
  • Увеличить окно контекста модели выше значения по умолчанию. Локальные среды выполнения поставляются с небольшими значениями по умолчанию (например, num_ctx в Ollama), которые не могут вместить большой набор инструментов плюс диалог — увеличьте его значительно выше значения по умолчанию.

Включение обнаружения на основе поиска

Установите ENABLE_TOOL_SEARCH=true (или переключите опцию в приложении HA). Полный каталог заменяется в списке инструментов четырьмя точками входа плюс небольшой набор всегда видимых "закреплённых" инструментов (ha_search, ha_get_overview, ha_report_issue и др.). Все инструменты остаются доступными для прямого вызова по имени после обнаружения:

Инструмент Назначение
ha_search_tools Поиск по ключевым словам BM25 по всем инструментам. Возвращает имя, описание, параметры и аннотации (readOnlyHint / destructiveHint), чтобы агент мог выбрать подходящий.
ha_call_read_tool Выполнение инструмента с readOnlyHint по имени. Безопасно — клиенты могут автоматически подтверждать.
ha_call_write_tool Выполнение инструмента записи, который создаёт или обновляет данные.
ha_call_delete_tool Выполнение инструмента, который удаляет данные.

Разделение прокси позволяет MCP-клиентам применять разные политики разрешений для каждой категории (например, автоматически подтверждать чтение, запрашивать подтверждение для записи, подтверждать удаление) без разбора строк документации инструментов.

Настройка По умолчанию Описание
ENABLE_TOOL_SEARCH false Заменяет полный каталог инструментов на обнаружение на основе поиска (инструменты откладываются за поиском по требованию).
TOOL_SEARCH_MAX_RESULTS 5 Максимальное количество результатов, возвращаемых ha_search_tools (диапазон 2–10).
PINNED_TOOLS пусто Имена инструментов, разделённые запятыми, которые всегда должны быть видимы. Основной способ управления — через веб-интерфейс настроек.

Когда включать

  • Claude Haiku, локальные модели, совместимые с OpenAI, Gemini или любые модели без встроенной поддержки отложенной загрузки инструментов — значительная экономия простаивающего контекста. То же касается клиентов, которые встраивают все схемы инструментов независимо от модели (например, GitHub Copilot CLI, даже при работе с Claude Sonnet/Opus).
  • MCP-клиенты с ограничением на общее количество инструментов (некоторые ограничивают до 100) — отображается минимальный набор (~10 инструментов) вместо 84.
  • Развёртывания с чувствительными к затратам условиями — меньше простаивающих токенов за ход.

Оставляйте отключённым в клиентах с отложенной загрузкой инструментов (claude.ai, Claude Desktop, Claude Code); полный каталог не создаёт простаивающих затрат, прямые вызовы пропускают этап поиска, а встроенный поиск инструментов клиента — лучший выбор, и нет смысла запускать поверх него поиск ha-mcp. То, откладываются ли инструменты, зависит от комбинации клиента и модели: одна и та же модель может вести себя по-разному в разных клиентах — GitHub Copilot CLI при работе с Claude Sonnet/Opus встраивает полный каталог и всё равно выигрывает от поиска инструментов здесь. Некоторые модели Codex и ChatGPT также поддерживают отложенную загрузку инструментов — проверьте напрямую возможности вашего клиента и модели, чтобы не оставлять эту функцию включённой без необходимости.


🔄 Обновите список инструментов клиента после изменения этого (или любого другого) параметра. Переключение ENABLE_TOOL_SEARCH (или изменение закреплённых/отключённых инструментов, режима "Только чтение" и т. д.) меняет инструменты, которые предоставляет сервер, но ваш AI-клиент продолжает использовать кэшированный список инструментов, пока не обновит его. Перезапуск приложения или Home Assistant не обновляет клиент — переподключитесь или обновите сервер MCP в вашем клиенте (например, повторно добавьте/обновите коннектор в ChatGPT или закройте и снова откройте Claude Desktop). Если пропустить это, недавно включённые инструменты не появятся в клиенте вообще, а инструменты, которые сервер больше не предоставляет, всё ещё будут отображаться как доступные, но при вызове вернут Unknown tool. ChatGPT иногда продолжает использовать устаревший список даже после удаления и повторного добавления коннектора под тем же именем — если инструменты всё ещё отсутствуют после повторного добавления, удалите коннектор и создайте новый с другим именем.

Для приложения HA этот же параметр описан в homeassistant-addon/DOCS.md вместе с интерфейсом настроек в приложении для точного включения/отключения/закрепления инструментов.


🧪 Канал разработки

Хотите получить ранний доступ к новым функциям и исправлениям? Сборки для разработчиков (.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: Стандартизированная коммуникация между AI и приложениями
  • Claude Code: AI-ассистент для программирования
  • PolicyLayer: DSL для предикатов на основе путей аргументов (args.domain in [...] с операторами eq/in/regex/contains/exists/...) вдохновил схему правил подтверждения для каждого инструмента (#966).

👥 Участники

Основные разработчики

  • @julienld — Создатель проекта.
  • @sergeykad — Основной разработчик.
  • @kingpanther13 — Основной разработчик.
  • @Patch76 — Основной разработчик.

Участники

  • @bigeric08 — Явная зависимость mcp для поддержки протокола версии 2025-11-25.
  • @airlabno — Поддержка поля data в блоках времени расписания.
  • @ryphez — Руководство по быстрой настройке MCP в интерфейсе Codex Desktop.
  • @Danm72 — Инструменты реестра сущностей (ha_set_entity, ha_get_entity) для управления свойствами сущностей.
  • @Raygooo — Поддержка SOCKS-прокси.
  • @cj-elevate — Инструменты управления интеграциями и сущностями (включение/отключение/удаление); маршрутизация конфигураций для person/zone/tag.
  • @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 вместо прямых подключений к контейнерам, исправление режима прокси ha_manage_addon (теперь ha_manage_app) при установке приложений.
  • @tomwilkie — Исследование промежуточного ПО JMESPath (#1147), данные измерения токенов во время ревью которых повлияли на дизайн #1199 и #1225.
  • @SealKan — Проекция fields=/attribute_keys= для шести инструментов с интенсивным чтением (#1225), инструмент ha_call_event (#1239), рефакторинг помощника списка панелей управления (#1207), детектор математических операций с длительностью в поле for: в проверке лучших практик (#1264), постоянная регистрация клиентов OAuth DCR между перезапусками (#1265) и бюджетирование токенов для запросов на триаж проблем (#1522).
  • @KarelTestSpecial — Кэшированный экземпляр YAML для предотвращения всплесков нагрузки на CPU при массовых правках (#1371).
  • @corgan2222 — Фирменные ресурсы HA для пользовательской интеграции (#1317).
  • @drseanwing — Вывод прогресса через Context FastMCP в долго выполняющихся инструментах (#1124); документация по обнаружению инструментов / категоризированному поиску (#1123).
  • @fnordpig — Поддержка подзаписей конфигурации (#1393) и инструмент управления конвейерами Assist (#1392).
  • @paul43210 — Режим array_patch в ha_manage_app для атомарных операций 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 для параметров инструментов типа dict/list.
  • @pburtchaell — Финансовая поддержка через GitHub Sponsors. Спасибо! ☕
  • @norpol — Создал OpenAI Tunnel для HA-MCP — дополнительную интеграцию, соединяющую ChatGPT с защищённым брандмауэром сервером MCP Home Assistant (#1811).

💬 Сообщество

  • GitHub Discussions — Задавайте вопросы, делитесь идеями
  • Трекер проблем — Сообщайте об ошибках, запрашивайте функции или предлагайте улучшения поведения инструментов

История звёзд

Star history chart for homeassistant-ai/ha-mcp

Войдите, чтобы оставить комментарий