Home Assistant Integration

Luci integrates with a Home Assistant instance to control smart home devices, automations, and dashboards in Elmar's house.

Connection Details

Setting	Value
HA URL	`https://e2vopg6b926yofyidyalknh434tccw7i.ui.nabu.casa` (Nabu Casa cloud)
Tailscale IP	`100.126.71.47`
SSH Port	`22222`
SSH User	`root`
SSH Key	`~/.ssh/id_ed25519_ha`
HA Core Version	2026.3.3

System Scale

1826 entities across 35 domains
381 services available
14 areas: Bedroom, Cayla, Dining Room, Garage, Garden, Guest, Jared, Kitchen, Lounge, Office, Pool, Rowen, Scullery, Upstairs

Access Methods (Priority Order)

1. MCP Tools (Primary -- interactive sessions)

In Claude Code interactive sessions, native MCP tools are available:

mcp__claude_ai_Home_Assistant__ha_get_overview       -- system overview
mcp__claude_ai_Home_Assistant__ha_search_entities    -- find entities
mcp__claude_ai_Home_Assistant__ha_get_state          -- single entity state
mcp__claude_ai_Home_Assistant__ha_call_service       -- call any service
mcp__claude_ai_Home_Assistant__ha_bulk_control       -- multiple actions
mcp__claude_ai_Home_Assistant__ha_config_get_automation  -- read automation YAML
mcp__claude_ai_Home_Assistant__ha_config_set_automation  -- create/update automations
mcp__claude_ai_Home_Assistant__ha_get_history        -- entity history
mcp__claude_ai_Home_Assistant__ha_restart            -- restart HA

2. ha-mcp.py Script (Secondary -- scripts/Luci tasks)

When MCP tools are unavailable (e.g., in scheduled tasks or scripts):

python3 ~/.claude/scripts/ha/ha-mcp.py <tool_name> '<json_args>'
python3 ~/.claude/scripts/ha/ha-mcp.py --list  # list all 80+ tools

On Luci, the script lives at ~/workspace/scripts/ha/ha-mcp.py.

3. Direct REST API (Tertiary)

source ~/.claude/vault/secrets/ha-credentials.env
curl -s -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/states"
curl -s -X POST -H "Authorization: Bearer $HA_TOKEN" \
  -H "Content-Type: application/json" \
  "$HA_URL/api/services/<domain>/<service>" -d '{"entity_id":"<id>"}'

4. SSH Config File Access

Direct filesystem access to HA configuration files via Tailscale SSH:

ssh -i ~/.ssh/id_ed25519_ha -p 22222 root@100.126.71.47 "cat /config/configuration.yaml"
ssh -i ~/.ssh/id_ed25519_ha -p 22222 root@100.126.71.47 "cat /config/automations.yaml"

Config files: configuration.yaml, automations.yaml, scripts.yaml, covers.yaml, templates.yaml

After editing: ha core check then ha core restart

5. WebSocket API (ha-ws.py)

For WebSocket-only APIs (repairs, etc.):

python3 ~/.claude/scripts/ha/ha-ws.py repairs list
python3 ~/.claude/scripts/ha/ha-ws.py repairs ignore <issue_id> <domain>

Known Devices

Device	Entity ID	Notes
Kitchen speaker	`media_player.kitchen`	Kitchen Heos (NOT media_player.kitchen_2)
Gate	`switch.shelly_gate`	Shelly 1, IP 192.168.1.74
Elmar's garage	`switch.sonoff_100113ef54`	Sonoff switch

Skill Reference

Skill path: ~/.claude/skills/home-assistant/SKILL.md
Rules: Always search/confirm entity_id before acting; always verify state changes succeeded; never restart HA without explicit user confirmation

Key Takeaways

Home Assistant is accessed via four layers: MCP tools, ha-mcp.py script, REST API, and SSH
MCP tools are the preferred method in interactive sessions; ha-mcp.py is the fallback for automation
The system manages 1826 entities across 14 areas of Elmar's house
SSH access via Tailscale provides direct config file editing for automations
Always confirm entity IDs before taking actions -- never guess

Wiki