hass

Hass-MCP is an MCP server that bridges Home Assistant with large language models (LMs) like Claude and other MCP clients. It exposes a set of tools that let an AI agent query and control your Home Assistant instance, fetch domain or entity summaries, run automations, and troubleshoot configurations. With Hass-MCP running (typically via Docker), you can connect to it from Claude Desktop, Claude Code CLI, Cursor, or other MCP clients and issue prompts that leverage the included tools to read states, perform actions, search entities, and get guided automation prompts. The available tools include get_version, get_entity, entity_action, list_entities, search_entities_tool, domain_summary_tool, list_automations, call_service_tool, restart_ha, get_history, and get_error_log, enabling a broad range of HA interactions from natural language prompts to structured queries.

Prerequisites:

• A Home Assistant instance with a Long-Lived Access Token (for authentication via HA_URL and HA_TOKEN)
• Docker installed on the host machine where you run Hass-MCP (recommended)
• Optional: uv/uvx if you prefer a Python-based runtime instead of Docker (see sections below)

Installation steps (Docker - recommended):

1. Ensure Docker is installed and running on your host.
2. Pull or run the Hass-MCP image with the required environment variables: docker run -i --rm -e HA_URL=http://homeassistant.local:8123 -e HA_TOKEN=YOUR_LONG_LIVED_TOKEN voska/hass-mcp
3. In Claude Desktop or your MCP client, add a new MCP server configuration pointing to the Docker command above, or reuse the provided mcp_config example.

Alternative (uv/uvx - Python runtime):

1. Install uv on your system.
2. Start Hass-MCP with uvx using the package name (as documented in the README): uvx hass-mcp --HA_URL=http://homeassistant.local:8123 --HA_TOKEN=YOUR_LONG_LIVED_TOKEN
3. Connect via Claude Desktop by providing the appropriate command and environment values as shown in the README.

Prerequisites recap:

• Home Assistant URL (HA_URL) and a Long-Lived Access Token (HA_TOKEN)
• Access to run Docker or uv/uvx depending on your chosen runtime

Tips and common issues:

• If Home Assistant runs in Docker, you may need to use the host network or adjust the HA_URL to the host IP address reachable from the Hass-MCP container.
• When using Claude Desktop with Docker, ensure you expose the HA_URL and HA_TOKEN via environment variables as shown in the configuration examples.
• For best compatibility, use the latest Hass-MCP image voska/hass-mcp and keep your Home Assistant token secure.
• If you encounter connection issues, verify that the Home Assistant instance is reachable from the runtime host (check firewall rules and network settings).
• The MCP toolset is designed to minimize token usage by returning lean JSON; adjust prompts to request only necessary fields when possible.