ha-nexus-agent

MCP-Server für Home Assistant — gibt KI-Assistenten die volle Kontrolle über Ihr Smart Home durch 202 Tools in 21 Domänen: Entitäten (mit Massensteuerung + Sprachfreigabe), Automatisierungen & Skripte (vollständiges CRUD + Traces), Blueprints, Dashboards, Helfer, Bereiche, Geräte-Registry, Kalender, To-Do-Listen, Verlauf, Systemverwaltung, YAML-Konfigurationsdateien, Git-basiertes Versioning, Echtzeit-WebSocket-Ereignisse, Energy Dashboard-Einstellungen, Zonen (Geofencing), Labels & Kategorien, Fuzzy-Suche & Discovery, Add-on-Verwaltung via Supervisor und HACS-Integration.

Funktioniert mit Claude Code CLI, Claude Desktop, VS Code, Cursor, Windsurf, OpenAI Codex CLI, Gemini CLI.

Installation — Home Assistant Add-on (empfohlen)

1. Gehen Sie in Home Assistant zu Einstellungen → Add-ons → Add-on Store

2. Klicken Sie auf das Drei-Punkte-Menü (⋮) → Repositories

3. Hinzufügen:

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

4. Suchen Sie nach Nexus Agent und klicken Sie auf Installieren

5. Klicken Sie auf Starten

6. Klicken Sie auf Web-UI öffnen

Die Web-UI zeigt Ihren API-Schlüssel an und generiert eine sofort kopierbare Konfiguration für jeden MCP-Client. Keine manuelle Token-Einrichtung erforderlich — das Add-on verbindet sich automatisch mit Home Assistant.

Installation — Standalone (außerhalb von 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

Öffnen Sie http://localhost:7123, um Ihren API-Schlüssel und die MCP-Client-Konfigurationen zu erhalten.

Einen Home Assistant Token erhalten

1. Gehen Sie in HA zu Profil → Sicherheit → Langfristige Zugriffstokens

2. Klicken Sie auf Token erstellen, nennen Sie ihn nexus

3. Fügen Sie ihn als HA_TOKEN in .env ein

Verbinden von MCP-Clients

Öffnen Sie http://your-ha-ip:7123 nach dem Start von Nexus. Die Einrichtungsseite generiert den exakten Befehl oder Konfigurationsschnipsel für jeden Client — einfach kopieren und einfügen.

Alle SSE-basierten Clients verbinden sich mit:

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

Erstellen Sie .vscode/mcp.json:

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

Cursor

Fügen Sie dies in ~/.cursor/mcp.json ein:

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

Windsurf

Fügen Sie dies in ~/.codeium/windsurf/mcp_config.json ein:

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

Claude Desktop (Standalone, Subprocess-Modus)

Fügen Sie dies in %APPDATA%/Claude/claude_desktop_config.json (Win) oder ~/Library/Application Support/Claude/claude_desktop_config.json (Mac) ein:

{
  "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"
      }
    }
  }
}

Tipp: Kopieren Sie die exakte Konfiguration (mit Ihren tatsächlichen Pfaden und dem Schlüssel) aus der Nexus Web-UI unter http://your-ha-ip:7123.

Funktionen

• 202 MCP-Tools in 21 Kategorien

• Echtzeit-WebSocket — abonnieren Sie Zustandsänderungen, Ereignisse und Trigger live

• Git-Versioning — jede Konfigurationsänderung wird automatisch mit sofortigem Rollback committet

• YAML-Validierung vor dem Schreiben jeder Konfigurationsdatei

• Setup Web-UI — generiert automatisch eine einsatzbereite MCP-Konfiguration für jeden Client

• HA Add-on nativ — Ein-Klick-Installation aus dem Add-on Store, keine manuelle Token-Einrichtung

• API-Key-Authentifizierung — MCP-Endpunkt geschützt, Token wird über URL-Abfrageparameter übergeben

Tool-Übersicht

Git-Versioning

Nexus führt eine Git-Historie Ihres HA-Konfigurationsverzeichnisses. Verwenden Sie vor jeder riskanten Änderung git_safe_write_with_checkpoint — es committet zuerst den aktuellen Zustand und wendet dann die Änderung an. Rollen Sie sofort zurück, falls etwas schiefgeht.

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

Umgebungsvariablen