ha-nexus-agent

MCP-сервер для Home Assistant — предоставляет ИИ-ассистентам полный контроль над вашим умным домом с помощью 202 инструментов в 21 домене: сущности (с массовым управлением + голосовым доступом), автоматизации и скрипты (полный CRUD + трассировка), чертежи (blueprints), панели управления, помощники, зоны, реестр устройств, календарь, списки дел, история, управление системой, YAML-файлы конфигурации, версионирование на базе git, события WebSocket в реальном времени, настройки панели управления энергией, зоны (геофенсинг), метки и категории, нечеткий поиск и обнаружение, управление аддонами через Supervisor и интеграция с HACS.

Работает с Claude Code CLI, Claude Desktop, VS Code, Cursor, Windsurf, OpenAI Codex CLI, Gemini CLI.

Установка — Аддон Home Assistant (рекомендуется)

1. В Home Assistant перейдите в Настройки → Дополнения → Магазин дополнений

2. Нажмите на меню из трех точек (⋮) → Репозитории

3. Добавьте:

   https://github.com/Fistacho/ha-nexus-agent

4. Найдите Nexus Agent и нажмите Установить

5. Нажмите Запустить

6. Нажмите Открыть веб-интерфейс

Веб-интерфейс покажет ваш API-ключ и сгенерирует готовую конфигурацию для любого MCP-клиента. Никакой ручной настройки токенов — аддон подключается к Home Assistant автоматически.

Установка — Автономно (вне HA)

git clone https://github.com/Fistacho/ha-nexus-agent
cd ha-nexus-agent
pip install -r requirements.txt
cp .env.example .env
# Edit .env: set HA_URL and HA_TOKEN
python server.py

Откройте http://localhost:7123, чтобы получить ваш API-ключ и конфигурации для MCP-клиентов.

Получение токена Home Assistant

1. В HA перейдите в Профиль → Безопасность → Токены длительного доступа

2. Нажмите Создать токен, назовите его nexus

3. Вставьте его как HA_TOKEN в файл .env

Подключение MCP-клиентов

Откройте http://your-ha-ip:7123 после запуска Nexus. Страница настройки сгенерирует точную команду или фрагмент конфигурации для каждого клиента — просто скопируйте и вставьте.

Все клиенты на базе SSE подключаются к:

http://your-ha-ip:7123/mcp?token=YOUR_API_KEY

Claude Code CLI

claude mcp add nexus --transport sse "http://your-ha-ip:7123/mcp?token=YOUR_API_KEY" --scope user

OpenAI Codex CLI

codex mcp add nexus --url "http://your-ha-ip:7123/mcp?token=YOUR_API_KEY"

Gemini CLI

gemini mcp add nexus --url "http://your-ha-ip:7123/mcp?token=YOUR_API_KEY"

VS Code

Создайте .vscode/mcp.json:

{
  "servers": {
    "nexus": {
      "type": "sse",
      "url": "http://your-ha-ip:7123/mcp?token=YOUR_API_KEY"
    }
  }
}

Cursor

Вставьте в ~/.cursor/mcp.json:

{
  "mcpServers": {
    "nexus": {
      "url": "http://your-ha-ip:7123/mcp?token=YOUR_API_KEY",
      "type": "sse"
    }
  }
}

Windsurf

Вставьте в ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "nexus": {
      "url": "http://your-ha-ip:7123/mcp?token=YOUR_API_KEY",
      "type": "sse"
    }
  }
}

Claude Desktop (автономный режим, режим подпроцесса)

Вставьте в %APPDATA%/Claude/claude_desktop_config.json (Win) или ~/Library/Application Support/Claude/claude_desktop_config.json (Mac):

{
  "mcpServers": {
    "nexus": {
      "command": "python",
      "args": ["server.py"],
      "cwd": "/path/to/ha-nexus-agent",
      "env": {
        "HA_URL": "http://homeassistant.local:8123",
        "HA_TOKEN": "your_ha_token_here"
      }
    }
  }
}

Совет: Скопируйте точную конфигурацию (с вашими реальными путями и ключом) из веб-интерфейса Nexus по адресу http://your-ha-ip:7123.

Возможности

• 202 MCP-инструмента в 21 категории

• WebSocket в реальном времени — подписка на изменения состояний, события и триггеры в реальном времени

• Git-версионирование — каждое изменение конфигурации автоматически фиксируется (commit) с возможностью мгновенного отката

• Валидация YAML перед записью любого файла конфигурации

• Веб-интерфейс настройки — автоматическая генерация готовой к использованию MCP-конфигурации для любого клиента

• Нативная поддержка аддонов HA — установка в один клик из Магазина дополнений, без ручной настройки токенов

• Аутентификация по API-ключу — MCP-эндпоинт защищен, токен передается через параметр запроса URL

Обзор инструментов

Git-версионирование

Nexus ведет git-историю вашей директории конфигурации HA. Перед любым рискованным изменением используйте git_safe_write_with_checkpoint — он сначала фиксирует текущее состояние, а затем применяет изменение. Откатитесь мгновенно, если что-то пойдет не так.

git_init_config()                                    # run once
git_safe_write_with_checkpoint("automations.yaml", new_content)
git_rollback_file("automations.yaml")                # undo single file
git_rollback_to_commit("abc1234")                    # full rollback
git_log(limit=10)                                    # see history

Переменные окружения