Home Assistant MCP

Сервер Model Context Protocol (MCP) с защитой OAuth для безопасного подключения ChatGPT, Codex и других MCP-клиентов к Home Assistant.

Проект предоставляет 99 типизированных инструментов для обнаружения, панелей управления, расписаний, климата, энергетики, медиа, уборки, полива, автоматизаций, диагностики и тщательно ограниченного управления устройствами. Он сохраняет API Home Assistant приватным и сознательно избегает превращения в универсальную оболочку, средство чтения журналов, сетевой сканер или неограниченный сервисный прокси.

[!ВАЖНО] Это эталонная реализация, чувствительная к безопасности, для самостоятельно размещённой установки Home Assistant. Прочтите модель безопасности, замените все примеры значений и проверьте списки разрешений перед подключением к реальному дому.

Основные возможности

• Типизированный доступ к Home Assistant: объекты, устройства, зоны, история, погода, календари, расписания, статистика, интеграции, панели управления, списки задач, автоматизации, резервные копии и состояние системы.

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

• Поддержка спринклеров: статус контроллера в реальном времени, метаданные зон, конфигурация, история полива, обновление телеметрии, запуск зон или последовательностей и идемпотентные операции остановки.

• Энергетика и SolarEdge: производство, сравнение модулей, поток мощности, разбивка энергии, сводки по хранилищам, телеметрия, оповещения и опциональная интеграция-мост для Home Assistant.

• Постоянная синхронизация возможностей: каждые пять минут сравнивает текущий реестр сервисов Home Assistant с проверенным базовым уровнем релиза и сообщает об отклонениях, не раскрывая динамически новые записи.

• Санитизированная диагностика: опциональные доказательства по фиксированным маршрутам, хосту/среде выполнения, сбоям и фиксированной подсети LAN со строгими ограничениями и без сырых адресов, произвольных целей, команд или управления устройствами.

• Удалённый доступ на основе OAuth: поток авторизации с S256 PKCE, динамическая регистрация клиентов, ограниченные токены доступа и метаданные ресурсов MCP.

Версия 2.6.1 в настоящее время рекламирует 99 инструментов. См. CHANGELOG.md для истории релизов.

Архитектура

flowchart LR
    Client[ChatGPT, Codex, or MCP client]
    Edge[HTTPS edge<br/>Cloudflare Worker, tunnel, or reverse proxy]
    MCP[Home Assistant MCP<br/>OAuth + typed tools]
    HA[Private Home Assistant API]
    Data[(OAuth, audit, and<br/>capability-sync state)]
    Collector[Optional root-owned<br/>diagnostics collector]
    Export[Sanitized read-only export]

    Client -->|HTTPS + OAuth/PKCE| Edge
    Edge -->|loopback or shared-secret origin| MCP
    MCP -->|long-lived service token| HA
    MCP --> Data
    Collector --> Export --> MCP

Эталонное развёртывание привязывает службу MCP к 127.0.0.1:8000. Публичным является только HTTPS-край. Home Assistant может оставаться локальным для хоста или быть доступным через частную сеть.

Поверхность инструментов

Действия с более высоким риском помечены как разрушительные и требуют явного аргумента подтверждения. Точный реестр является авторитетным; проверьте его из аутентифицированного MCP-клиента после развёртывания.

Требования

• Home Assistant, доступный с хоста MCP.

• Выделенный долгоживущий токен доступа Home Assistant. По возможности используйте отдельную сервисную учётную запись.

• Python 3.12 или новее и uv для разработки и тестов.

• Docker с Compose для эталонного контейнерного развёртывания.

• Публичный HTTPS-URL для удалённых MCP-клиентов.

• HTTPS-край, который достигает MCP через loopback или внедряет настроенный общий секрет источника. Включённые примеры Caddy и Cloudflare демонстрируют эти два шаблона.

• Linux и systemd только при использовании опционального коллектора диагностики хоста.

Включённый файл Compose — это производственный эталон, а не универсальный установщик в одну команду. Он предполагает сетевой режим хоста, существующую конфигурацию Home Assistant в /opt/homeassistant/config и установленный экспорт диагностики в /var/lib/ha-host-diagnostics/export. Адаптируйте эти точки монтирования к вашей установке, не раскрывая API Home Assistant или сокет Docker.

Быстрый старт для разработки

Клонируйте репозиторий и установите зафиксированные зависимости:

git clone https://github.com/shogun301/ha-chatgpt-mcp.git
cd ha-chatgpt-mcp
uv sync --frozen

Тестовый набор и аудит публичного исходного кода не требуют производственных учётных данных:

uv run python scripts/public_release_audit.py --history
uv run --with pytest python -m pytest tests collector/tests home_assistant/tests

Для запуска службы скопируйте .env.example в игнорируемый .env, замените все примеры доменов и идентификаторов объектов и предоставьте требуемые пути выполнения и секретные файлы, описанные ниже. Приложение не загружает .env автоматически; экспортируйте переменные в вашем менеджере процессов, используйте uvicorn --env-file .env или позвольте Docker Compose загрузить его.

Для локального процесса после настройки окружения:

uv run uvicorn app.server:app --host 127.0.0.1 --port 8000 --no-proxy-headers

Для эталонного контейнерного развёртывания после адаптации его точек монтирования и опциональных интеграций:

docker compose build --pull
docker compose up -d
curl --fail http://127.0.0.1:8000/healthz

Не привязывайте Uvicorn напрямую к публичному интерфейсу.

Конфигурация

Основные настройки

Переменные, специфичные для объектов, в .env.example сопоставляют общую поверхность инструментов с объектами присутствия, уведомлений, пылесоса, спринклера, термостата и расписания одного развёртывания. Храните реальные идентификаторы объектов в локальной конфигурации, а не в Git.

Требуемые секретные файлы

Сервер читает секреты из файлов, а не из значений окружения:

Генерируйте случайные значения с помощью криптографически безопасного генератора. Argon2-хэш пароля можно получить, не помещая пароль в историю оболочки:

uv run python -c "from argon2 import PasswordHasher; from getpass import getpass; print(PasswordHasher().hash(getpass('OAuth password: ')))"
uv run python -c "import secrets; print(secrets.token_urlsafe(48))"

Храните выходные данные в отдельных файлах с правами только для владельца. Никогда не коммитьте secrets/, .env, токены, пароли, хэши, приватные домены, инвентаризации объектов, расписания или топологию сети.

Опциональная конфигурация SolarEdge

Поддержка SolarEdge использует опциональные учётные данные клиента, зашифрованное хранилище токенов, секрет моста, URI перенаправления и защищённые резервные учётные данные портала. Если вы не используете SolarEdge, опустите соответствующие переменные SOLAREDGE_*_FILE. Эталонный файл Compose задаёт эти пути, поэтому либо предоставьте файлы, либо удалите эти записи в вашем локальном переопределении.

Области OAuth

• mcp:read разрешает инструменты чтения.

• mcp:write разрешает проверенную поверхность записи и также удовлетворяет текущему самому сильному совместимому гранту.

• mcp:diagnostics вместе с mcp:read разрешает привилегированную диагностику хоста и LAN только для чтения, не предоставляя запись устройств.

Подключайте клиентов к https://your-mcp-host.example/mcp. Сервер публикует метаданные OAuth-сервера авторизации, защищённого ресурса, конфигурации OpenID и динамической регистрации клиентов под тем же источником.

Варианты края

Приложение требует, чтобы запросы, не относящиеся к loopback, несли настроенный общий секрет источника. Включены два примера:

• cloudflare/ содержит узкий прокси-воркер Cloudflare Worker. Он пересылает только пути MCP, OAuth, health и обратного вызова SolarEdge, применяет ограничение запроса в 1 МиБ, добавляет секрет источника и удаляет ненужные заголовки.

• Caddyfile предоставляет HTTPS-обратный прокси на том же хосте к loopback-слушателю MCP.

Включённая служба cloudflared использует файл токена и публикует метрики только на loopback. Замените все примеры маршрутов и держите источник MCP, API Home Assistant и слушатель метрик вне публичной сети.

Синхронизация возможностей

Интеграции Home Assistant могут добавлять или удалять сервисы независимо от этого проекта. Поэтому сервер опрашивает реестр сервисов Home Assistant каждые пять минут и сохраняет привязанный к релизу базовый уровень в /data/ha-capability-sync.json.

get_capability_sync_status сообщает о добавленных или удалённых сервисах и изменениях схемы полей между перезапусками. Монитор намеренно наблюдательный: он никогда не вызывает сервис и никогда не превращает непроверенный сервис Home Assistant в новый инструмент записи MCP. Новые функции следует проверять, реализовывать как типизированные инструменты, тестировать и выпускать через Git.

Опциональная диагностика хоста и LAN

Коллектор systemd в collector/ не имеет слушателя и не принимает выбранную вызывающим команду, путь, контейнер, выражение журнала или URL. Он публикует ограниченные, санитизированные снимки и реестры в фиксированный каталог. Контейнер MCP получает только этот каталог как монтирование только для чтения — никогда сокет Docker, журнал хоста, procfs, sysfs или управление systemd.

Инструменты LAN работают только внутри одной настроенной /24, возвращают непрозрачные идентификаторы узлов, используют закрытый список разрешений TCP-сервисов, не отправляют прикладные полезные нагрузки и опускают сырые адреса. Они не могут сканировать произвольные сети или управлять устройствами.

См. docs/operations.md и collector/README.md для полной модели данных, ограничений хранения, развёртывания, проверки, инцидентов и процедур отката.

Модель безопасности

Этот сервер намеренно уже, чем API Home Assistant:

• Нет выполнения команд оболочки, произвольного проброса WebSocket, произвольных файлов, сырых журналов, администрирования Docker, перезапуска служб, завершения работы, получения учетных данных, изображений с камер или снятия сигнализации.

• Универсальные вызовы служб Home Assistant внесены в белый список по домену и службе; предпочтительны выделенные типизированные инструменты.

• Входные данные проверяются по схеме, размеры результатов ограничены, а конфиденциальные диагностические поля рекурсивно замаскированы.

• Разрушительные или физические операции используют явные аннотации и шлюзы подтверждения.

• Записи аудита содержат имена инструментов и ограниченные метаданные, а не учетные данные или возвращаемые диагностические данные.

• Контейнер работает как непривилегированный пользователь с файловой системой только для чтения, всеми отброшенными возможностями Linux и включенным no-new-privileges.

• Аудит публичного выпуска сканирует как текущее дерево, так и историю Git перед публикацией.

Никогда не используйте термостат, свет, замок, пылесос, разбрызгиватель, камеру, динамик, телевизор, резервное копирование, уведомление или другой физический побочный эффект в качестве проверки подключения.

Для сообщения об уязвимостях и обработки конфиденциальной информации о развертывании прочтите SECURITY.md.

Развертывание и проверка

Скрипт развертывания PowerShell в scripts/deploy-production.ps1 является эталонной реализацией для AWS Lightsail. Он требует явных параметров профиля AWS, региона, экземпляра, URL внешнего интерфейса и URL MCP; упаковывает проверенный исходный код; создает резервные копии; развертывает коллектор и контейнер; выполняет проверку; и поддерживает откат. Внимательно изучите его перед адаптацией к другому хосту.

Перед каждым публичным пушем или производственным релизом:

uv sync --frozen
uv run python scripts/public_release_audit.py --history
uv run --with pytest python -m pytest tests collector/tests home_assistant/tests

Затем проверьте, не изменяя состояние устройства:

1. /healthz успешно выполняется локально и через публичный периметр.

2. Неаутентифицированные и запросы MCP с недействительным токеном отклоняются.

3. Аутентифицированное обнаружение сообщает ожидаемую версию и количество инструментов.

4. Проверки только для чтения: обзор, capability-sync, маршрут и интеграция — успешно выполняются.

5. Публичный коммит Git, развернутый артефакт и сообщаемая версия службы идентичны.

Производственные процедуры и шлюзы отката подробно описаны в docs/operations.md.

Внесение вклада

Проблемы и запросы на включение приветствуются, если они сохраняют ограниченную модель безопасности проекта.

Для новых инструментов:

1. Предпочитайте узкую типизированную операцию универсальному пробросу.

2. Точно определяйте аннотации только для чтения, идемпотентные, записи или разрушительные.

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

4. Требуйте явного подтверждения для значимых физических или административных действий.

5. Добавляйте тесты авторизации, негативных сценариев, редактирования и регрессионные тесты.

6. Обновите документацию по возможностям и запустите аудит публичной истории.

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

Лицензия

В настоящее время открытая лицензия не включена. Публичная видимость не дает разрешения на копирование, изменение или распространение кода. Владельцы репозитория должны добавить явную лицензию перед принятием повторного использования или распространения.

Ссылки

• Model Context Protocol

• OpenAI: Создание MCP-сервера

• OpenAI: Аутентификация пользователей

• Мониторинг Cloudflare Tunnel

• Метрики Cloudflare Tunnel