Nexus Agent — MCP for Home Assistant

Give AI assistants full control over your smart home. 276 tools across 27 domains — entities (with bulk voice exposure), automations & scripts (CRUD + traces + last-failed shortcuts), dashboards, energy, voice pipelines, blueprints, calendar, HACS, Supervisor, themes, self-documenting Card Builder (visual drag-and-drop cards, recipe builder with embedded block schema + style categories + style targets + style snippets + upstream sync check), aggregated snapshot (one-call context), BM25 tool search (find the right tool without memorising 270 names), HA-aware YAML validation (!include, !secret), git versioning, and more.

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

Option 1: Installation via Home Assistant (Recommended)

Click the button below to add the Nexus Agent repository to your Home Assistant instance, then install the add-on:

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

Option 2: 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. No manual token setup.

Option 3: 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

276 tools across 27 categories:

Features

• 270 MCP tools across 27 categories — the most complete HA MCP server

• Built-in tool search — discover_tool_search("query") finds the right tool without flooding the AI's working memory

• Real-time WebSocket — subscribe to state changes, events and triggers live

• Git versioning — every config change auto-committed, instant rollback

• YAML validation before writing any config file

• 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

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.

git_init_config()
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

Environment Variables

Changelog

See Releases for full history.