The ha-mcp add-on runs inside Home Assistant OS and exposes 85 tools to Claude Desktop via the Model Context Protocol. Claude can query devices, control entities, manage automations, inspect integrations, and more — all without leaving the chat.

• Add-on: addon_81f33d0f_ha_mcp (v7.5.0)
• URL: http://192.168.0.10:9583/private_<secret-path>
• Auth model: Secret-path-in-URL (no Bearer token). The secret path is generated on first install and persists at /data/secret_path.txt inside the add-on container across restarts.
• Tools: 85 (discovery, device/integration mgmt, state control, CRUD, templates, traces, history, addons, HACS, system, blueprints, camera, todo, bundled docs)

The config block lives in ~/Sync/ED/config/claude_desktop_config.json (symlinked to ~/Library/Application Support/Claude/claude_desktop_config.json on both Mac Studio and MacBook).

"ha-mcp": {
  "command": "npx",
  "args": [
    "-y", "mcp-remote",
    "http://192.168.0.10:9583/private_<secret-path>",
    "--transport", "http-only",
    "--allow-http"
  ]
}

Critical: The --allow-http flag is required because mcp-remote refuses non-HTTPS URLs without it. This was the blocker on initial MacBook setup (2026-05-23).

Claude Desktop (Mac Studio / MacBook)
  → NetBird mesh VPN
  → fpve.netbird.cloud (100.123.49.175)
     routes 192.168.0.0/24 (farm LAN)
  → Home Assistant at 192.168.0.10:9583

HA does not run NetBird itself. Reachability from any NetBird peer goes through fpve’s advertised route for the 192.168.0.0/24 subnet. Both Mac Studio and MacBook must have that route enabled in their NetBird client (NetBird app → Routes → confirm 192.168.0.0/24 is selected).

On the farm LAN (MacBook at Brownsville), HA is reachable directly at 192.168.0.10:9583 — no NetBird needed.

To rotate the secret path:

1. SSH into HA: ssh ha (user delgross, port 22, key ~/.ssh/ha_id_ed25519)
2. Delete the secret file inside the add-on container (path varies by supervisor version)
3. Restart the add-on — it regenerates a new secret path
4. Update claude_desktop_config.json with the new URL on both machines
5. Restart Claude Desktop on both Studio and MacBook

Full consumer map entry in ~/Sync/ED/SECRETS.md.

Claude Desktop log: ~/Library/Logs/Claude/mcp-server-ha-mcp.log

Common issues:

• “HTTPS required” error → missing --allow-http flag in config args
• Connection refused → NetBird route for 192.168.0.0/24 not enabled, or HA is down
• Timeout → fpve (farm Proxmox) is offline or NetBird mesh not converged
• 403 / auth error → secret path changed; check /data/secret_path.txt on HA

Smoke test prompt: “List the areas in Home Assistant” — should return 13 areas (Barn, Garage, Kitchen, etc.)