MCP Home Assistant¶

This guide enables Home Assistant integration through the local Dockerized Hass-MCP server registered in .mcp.json.

Scope¶

Current implementation in this repository provides:

• Docker-only MCP transport
• Pinned immutable image digest
• Secrets loaded from local .env
• Bitwarden-driven hydration of HA_URL and HA_TOKEN

Current image: docker.io/voska/hass-mcp:latest

1. Hydrate Home Assistant credentials from Bitwarden¶

Expected Bitwarden item:

• Item name: Home Assistant Credentials
• Field HA_URL: Home Assistant base URL (for example, http://homeassistant.local:8123)
• Field HA_TOKEN: Home Assistant long-lived access token

Hydrate local .env from vault fields:

just bw-env-hydrate

This upserts HA_URL, HA_TOKEN, KAGI_API_KEY, and YOUTUBE_API_KEY in local .env.

2. Validate MCP wiring¶

Run from the hermetic Nix shell:

just sync-ai
just mcp-health

Expected summary includes:

• hass MCP docker image: docker.io/voska/hass-mcp@sha256:<digest>

3. Example prompts¶

In your MCP-capable client, run prompts similar to:

Use the hass MCP server to summarize my climate domain entities.

Use the hass MCP server to turn off light.kitchen and report the resulting state.

Use the hass MCP server to search for entities related to living room.

Troubleshooting¶

• No Home Assistant token provided: re-run just bw-env-hydrate and reload environment.
• Connection failures: verify HA_URL points to a reachable Home Assistant instance from Docker.
• Token rejected: generate a new Home Assistant long-lived token and update Bitwarden field HA_TOKEN, then re-run hydration.