voska/hass-mcp

A Model Context Protocol (MCP) server for Home Assistant integration with Claude and other LLMs.
Overview
Hass-MCP enables AI assistants like Claude to interact directly with your Home Assistant instance, allowing them to:
- Query the state of devices and sensors
- Control lights, switches, and other entities
- Get summaries of your smart home
- Troubleshoot automations and entities
- Search for specific entities
- Create guided conversations for common tasks
Screenshots
Features
- **Entity Management**: Get states, control devices, and search for entities
- **Domain Summaries**: Get high-level information about entity types
- **Automation Support**: List and control automations
- **Guided Conversations**: Use prompts for common tasks like creating automations
- **Smart Search**: Find entities by name, type, or state
- **Live Dashboard Editing**: Read and edit Lovelace dashboards (cards and views) over Home Assistant's WebSocket API — changes appear instantly in open browsers, with automatic backups and a dry-run preview
- **Token Efficiency**: Lean JSON responses to minimize token usage
Installation
Prerequisites
- Home Assistant instance with Long-Lived Access Token
- One of the following:
- Docker (recommended)
- Python 3.13+ and uv
Setting Up With Claude Desktop
Docker Installation (Recommended)
1. Pull the Docker image:
2. Add the MCP server to Claude Desktop:
a. Open Claude Desktop and go to Settings
b. Navigate to Developer > Edit Config
c. Add the following configuration to your claude_desktop_config.json file:
d. Replace YOUR_LONG_LIVED_TOKEN with your actual Home Assistant long-lived access token
e. Update the HA_URL:
- If running Home Assistant on the same machine: use http://host.docker.internal:8123 (Docker Desktop on Mac/Windows)
- If running Home Assistant on another machine: use the actual IP or hostname
f. Save the file and restart Claude Desktop
3. The "Hass-MCP" tool should now appear in your Claude Desktop tools menu
> **Note**: If you're running Home Assistant in Docker on the same machine, you may need to add --network host to the Docker args for the container to access Home Assistant. Alternatively, use the IP address of your machine instead of host.docker.internal.
uv/uvx
1. Install uv on your system.
2. Add the MCP server to Claude Desktop:
a. Open Claude Desktop and go to Settings
b. Navigate to Developer > Edit Config
c. Add the following configuration to your claude_desktop_config.json file:
d. Replace YOUR_LONG_LIVED_TOKEN with your actual Home Assistant long-lived access token
e. Update the HA_URL:
- If running Home Assistant on the same machine: use http://host.docker.internal:8123 (Docker Desktop on Mac/Windows)
- If running Home Assistant on another machine: use the actual IP or hostname
f. Save the file and restart Claude Desktop
3. The "Hass-MCP" tool should now appear in your Claude Desktop tools menu
Other MCP Clients
Cursor
1. Go to Cursor Settings > MCP > Add New MCP Server
2. Fill in the form:
- Name: Hass-MCP
- Type: command
- Command:
- Replace YOUR_LONG_LIVED_TOKEN with your actual Home Assistant token
- Update the HA_URL to match your Home Assistant instance address
3. Click "Add" to save
Claude Code (CLI)
To use with Claude Code CLI, you can add the MCP server directly using the mcp add command:
**Using Docker (recommended):**
Replace YOUR_LONG_LIVED_TOKEN with your actual Home Assistant token and update the HA_URL to match your Home Assistant instance address.
HTTP Transport (Streamable)
For deployments that can't use stdio — running behind an MCP gateway, hosting on Smithery, sharing one server across multiple clients, or connecting from network-based tools like LibreChat or OpenWebUI — Hass-MCP supports the MCP streamable HTTP transport. The server runs in stateless mode (no Mcp-Session-Id, JSON responses), suitable for horizontally-scaled hosts.