voska/hass-mcp

docker pull voska/hass-mcp:latest
Prerequisites: a Home Assistant instance with Long-Lived Access Token, plus Docker (recommended) or Python 3.13+ with uv
uvx hass-mcp (via uv, alternative to Docker)

Usage

• •Add to Claude Desktop claude_desktop_config.json: command docker, args [run, -i, --rm, -e, HA_URL, -e, HA_TOKEN, voska/hass-mcp]
• •Docker on same machine: use http://host.docker.internal:8123 as HA_URL; may need --network host
• •HTTP transport: HA_URL=... HA_TOKEN=... uvx hass-mcp --http --port 8000; MCP endpoint at /mcp (binds 127.0.0.1 by default)
• •Claude Code CLI: claude mcp add hass-mcp -e HA_URL=... -e HA_TOKEN=... -- docker run -i --rm -e HA_URL -e HA_TOKEN voska/hass-mcp
• •Example prompts: 'What's the current state of my living room lights?', 'Create an automation that turns on the lights at sunset'

Key features

• ✓Tools for entity state/actions, entity search, domain summaries, automation list/control, call any HA service, restart_ha, history/statistics ranges, server-side filtered error log
• ✓Live Lovelace dashboard editing (cards/views) over Home Assistant's WebSocket API with automatic backups and dry_run preview
• ✓Guided-conversation prompts: create_automation, debug_automation, troubleshoot_entity, routine_optimizer, automation_health_check, dashboard_layout_generator
• ✓Resources: hass://entities/{entity_id}, hass://entities/domain/{domain}, hass://search/{query}/{limit}
• ✓Status: streamable HTTP transport in stateless mode for gateways/Smithery/shared deployments; honors PORT env var
• ✓Token-efficient lean JSON responses to minimize usage

Best for

Letting an AI assistant control and troubleshoot a self-hosted Home Assistant smart home (lights, sensors, automations) from natural language.

Caveats

• ⚠Dashboard editing requires an admin long-lived token and only works on storage-mode (UI-managed) dashboards; YAML-mode dashboards are rejected
• ⚠HTTP mode exposes full Home Assistant control (turn off lights, unlock doors, restart HA) over the network with no built-in auth — must be behind a reverse proxy, VPN, or localhost binding
• ⚠In Docker, mount a volume at HASS_MCP_BACKUP_DIR (default ~/.hass-mcp/dashboard-backups/) or backups are lost when the container is recreated
• ⚠verify=False is intentionally not supported; use HA_URL=http:// for unencrypted local LAN traffic
• ⚠Custom/private CA supported via OS trust store or SSL_CERT_FILE bind-mount