Nexus Agent — MCP for Home Assistant

Give AI assistants full control over your smart home. 325 tools across 29 domains — entities, automations & scripts (CRUD + traces + linter + live reference validator), scene CRUD, dashboards + screenshot + resource management, energy, long-term statistics (sum/mean/min/max by day/week/month), voice pipelines, blueprints, calendar, HACS, Supervisor, ESPHome (list devices, compile, OTA, logs, LVGL display UI management), themes, self-documenting Card Builder (visual cards, recipe builder, embedded block schema, upstream sync), aggregated snapshot (one-call context), BM25 tool search, HA-aware YAML validation, git versioning, and more.

Works with Claude Code, Claude Desktop, VS Code, Cursor, Windsurf, OpenAI Codex CLI, Gemini CLI.

What can you ask?

Once connected, just talk to your AI assistant:

• "Turn off all lights in the house"
• "Create an automation: alert me when the front door opens after 10 PM"
• "Why is my bedroom sensor showing unavailable?"
• "Take a screenshot of my main dashboard"
• "Show all pending Home Assistant updates"
• "Install Mushroom Cards from HACS"
• "Commit my config changes to git with a summary of what changed"
• "Build me a Lovelace card for the living room with temperature and humidity"

What's New in v0.16.0

• system_get_updates — list pending HA updates (core, add-ons, HACS, custom components) with version info and release URLs
• system_get_system_health — health check of all HA subsystems (recorder, network, cloud, etc.)
• system_get_repairs — list active repair issues that require attention
• Entity groups CRUD — automations_list_groups, automations_set_group, automations_remove_group — create/update/delete group.* entities via group.set
• Live automation reference validator — automations_validate_automation_references cross-checks every entity_id and service in your YAML against the live HA registry; template values skipped automatically
• Lovelace resource management — dashboards_add_dashboard_resource, dashboards_remove_dashboard_resource, dashboards_update_dashboard_resource — manage custom JS/CSS resources without touching YAML

What's New in v0.15.0

• Pagination + field selection — list_entities and get_snapshot now accept limit, offset, and fields/state_fields
• Confirmation gates on all destructive operations — restart_ha, stop_ha, git_rollback_*, delete_automation, delete_script, remove_integration all require confirm=True
• Automation best-practice linter — automations_validate_best_practices statically checks YAML for 7 common mistakes
• Dashboard screenshot via Puppet engine — dashboards_screenshot renders any Lovelace view to PNG

Installation — Home Assistant Add-on (Recommended)

1. Click the Open Add-on Repository on MY button above
2. Find Nexus Agent in the Add-on Store → Install → Start
3. Open Web UI — copy your MCP URL and paste it into your AI client

Manual Installation (Add-on Store)

If the MY button does not work for your setup:

1. In Home Assistant go to Settings → Add-ons → Add-on Store

2. Click the three-dot menu (⋮) → Repositories

3. Add:

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

4. Find Nexus Agent → Install → Start → Open Web UI

The web UI shows your API key and generates ready-to-paste config for every MCP client.

Standalone (outside 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

Open http://localhost:7123 to get your API key and MCP client configs.

Getting a Home Assistant token

1. In HA: Profile → Security → Long-Lived Access Tokens
2. Create Token → name it nexus
3. Paste as HA_TOKEN in .env

Connecting MCP Clients

Open http://your-ha-ip:7123 after starting Nexus. The setup page generates the exact config for each client.

All clients connect to:

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

Create .vscode/mcp.json:

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

Cursor

Add to ~/.cursor/mcp.json:

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

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

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

Claude Desktop

Add to %APPDATA%/Claude/claude_desktop_config.json (Win) or ~/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"
      }
    }
  }
}

Tip: Copy the exact config with your real key from the Nexus web UI at http://your-ha-ip:7123.

Tools

325 tools across 29 categories:

Features

• 325 MCP tools across 29 categories — the most complete HA MCP server available
• Built-in tool search — discover_tool_search("query") finds the right tool without flooding the AI's context
• Confirmation gates — all destructive operations require confirm=True; without it they return the exact command to re-run
• Automation linter — automations_validate_best_practices catches 7 common YAML mistakes before they cause issues
• Live reference validator — automations_validate_automation_references cross-checks every entity_id and service call against the running HA instance
• Updates monitor — system_get_updates lists all pending updates across core, add-ons and HACS
• Repair issues — system_get_repairs surfaces active issues from HA's repair centre
• Lovelace resources — add/remove/update custom JS modules and CSS without editing YAML
• Dashboard screenshot — render any Lovelace view to PNG via the Puppet engine (see below)
• Real-time WebSocket — subscribe to state changes, events and triggers live
• Git versioning — every config change auto-committed, instant rollback, safe_write_with_checkpoint
• YAML validation before writing any config file (!include, !secret aware)
• Setup web UI — generates ready-to-use MCP config for every client
• HA Add-on native — one-click install, no manual token setup
• API key auth — MCP endpoint protected, token via URL or Bearer header

Dashboard Screenshots

dashboards_screenshot renders any Lovelace view to a base64-encoded PNG by delegating to the Puppet headless Chromium add-on. Nexus itself contains no browser dependencies — this approach works on every architecture (amd64, aarch64, armv7, armhf).

Setup

1. In HA: Settings → Add-ons → Add-on Store → ⋮ → Repositories
   Add: https://github.com/balloob/home-assistant-addons
2. Install Puppet, set its access_token option to a HA long-lived access token, then start it
3. Done — Nexus discovers Puppet automatically via the Supervisor

Docker / standalone:

# Run the Puppet container as a sidecar, then point Nexus at it:
NEXUS_SCREENSHOT_ENGINE_URL=http://puppet:10000

Usage

dashboards_screenshot(url_path="caly-dom", width=1280, height=800, wait_ms=3000)
dashboards_screenshot(url_path="lovelace/0", full_page=True)   # full scrollable page

Returns {"image_base64": "...", "format": "png", "size_bytes": ...}.

Git Versioning

Nexus keeps a git history of your HA config directory. Before every risky change, use git_safe_write_with_checkpoint — it commits current state first, then applies the change.

All rollback operations require confirm=True to prevent accidental data loss:

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

Automation Linter

automations_validate_best_practices checks YAML against 7 rules before you save:

automations_validate_best_practices(yaml_content="""
alias: Turn off lights
trigger:
  - platform: state
    entity_id: binary_sensor.motion
    to: "off"
action:
  - service: light.turn_off
    target:
      entity_id: light.living_room
""")
# → {"warnings": 2, "infos": 1, "issues": [...]}

Environment Variables

Changelog

See Releases for full history.