ha-nexus-agent

Servidor MCP para Home Assistant — ofrece a los asistentes de IA control total sobre tu hogar inteligente a través de 202 herramientas en 21 dominios: entidades (con control masivo + exposición por voz), automatizaciones y scripts (CRUD completo + trazas), blueprints, paneles, helpers, áreas, registro de dispositivos, calendario, listas de tareas, historial, gestión del sistema, archivos de configuración YAML, control de versiones basado en git, eventos WebSocket en tiempo real, preferencias del Panel de Energía, Zonas (geofencing), Etiquetas y Categorías, búsqueda y descubrimiento difusos, gestión de complementos a través de Supervisor e integración con HACS.

Funciona con Claude Code CLI, Claude Desktop, VS Code, Cursor, Windsurf, OpenAI Codex CLI, Gemini CLI.

Instalación — Complemento de Home Assistant (recomendado)

1. En Home Assistant, ve a Ajustes → Complementos → Tienda de complementos

2. Haz clic en el menú de tres puntos (⋮) → Repositorios

3. Añade:

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

4. Busca Nexus Agent y haz clic en Instalar

5. Haz clic en Iniciar

6. Haz clic en Abrir interfaz web

La interfaz web muestra tu clave API y genera la configuración lista para copiar para cualquier cliente MCP. Sin configuración manual de tokens: el complemento se conecta a Home Assistant automáticamente.

Instalación — Independiente (fuera de 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

Abre http://localhost:7123 para obtener tu clave API y las configuraciones del cliente MCP.

Obtener un token de Home Assistant

1. En HA, ve a Perfil → Seguridad → Tokens de acceso de larga duración

2. Haz clic en Crear token, nómbralo nexus

3. Pégalo como HA_TOKEN en .env

Conexión de clientes MCP

Abre http://tu-ip-de-ha:7123 después de iniciar Nexus. La página de configuración genera el comando o fragmento de configuración exacto para cada cliente: solo copia y pega.

Todos los clientes basados en SSE se conectan a:

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

Crea .vscode/mcp.json:

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

Cursor

Pégalo en ~/.cursor/mcp.json:

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

Windsurf

Pégalo en ~/.codeium/windsurf/mcp_config.json:

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

Claude Desktop (modo independiente, modo subproceso)

Pégalo en %APPDATA%/Claude/claude_desktop_config.json (Win) o ~/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"
      }
    }
  }
}

Consejo: Copia la configuración exacta (con tus rutas y clave reales) desde la interfaz web de Nexus en http://tu-ip-de-ha:7123.

Características

• 202 herramientas MCP en 21 categorías

• WebSocket en tiempo real — suscríbete a cambios de estado, eventos y disparadores en vivo

• Control de versiones Git — cada cambio de configuración se confirma automáticamente con reversión instantánea

• Validación YAML antes de escribir cualquier archivo de configuración

• Interfaz web de configuración — genera automáticamente la configuración MCP lista para usar para cada cliente

• Nativo de complementos de HA — instalación con un clic desde la Tienda de complementos, sin configuración manual de tokens

• Autenticación con clave API — punto final MCP protegido, token pasado a través del parámetro de consulta de la URL

Resumen de herramientas

Control de versiones Git

Nexus mantiene un historial de git de tu directorio de configuración de HA. Antes de cualquier cambio arriesgado, usa git_safe_write_with_checkpoint: confirma primero el estado actual y luego aplica el cambio. Revierte instantáneamente si algo falla.

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

Variables de entorno