Hass-MCP
Control and query Home Assistant from Claude and other LLMs over the Model Context Protocol.
Add to your client
Copy the config for your MCP client and paste it into its config file.
docker pull voska/hass-mcp:latestPaste into ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"hass-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"HA_URL",
"-e",
"HA_TOKEN",
"voska/hass-mcp"
],
"env": {
"HA_URL": "http://homeassistant.local:8123",
"HA_TOKEN": "YOUR_LONG_LIVED_TOKEN"
}
}
}
}Requires Docker to be installed and running.
Step-by-step guides: Add to Claude Desktop · Add to Cursor · Add to Windsurf
Before you start
- A Home Assistant instance with a Long-Lived Access Token
- Docker (recommended) OR Python 3.13+ with uv/uvx
- An MCP client such as Claude Desktop, Cursor, or Claude Code CLI
About Hass-MCP
Hass-MCP enables AI assistants such as Claude to interact directly with a Home Assistant instance: querying device and sensor states, controlling entities (lights, switches, etc.), getting domain summaries, troubleshooting automations and entities, searching entities, and running guided conversations for common smart-home tasks. It supports stdio transport via Docker or uvx for desktop clients (Claude Desktop, Cursor, Claude Code CLI) and a streamable HTTP transport for gateway or hosted deployments. Responses are returned as lean JSON to minimize token usage.
Tools & capabilities (15)
get_versionGet the Home Assistant version.
get_entityGet the state of a specific entity, with optional field filtering.
entity_actionPerform actions on entities (turn on, off, toggle).
list_entitiesGet a list of entities with optional domain filtering and search.
search_entities_toolSearch for entities matching a query.
domain_summary_toolGet a summary of a domain's entities.
list_automationsGet a list of all automations.
call_service_toolCall any Home Assistant service.
restart_haRestart Home Assistant.
get_historyGet the state history of an entity for the last N hours.
get_history_rangeGet state-change history for an entity over an explicit ISO-8601 date/time range (start_time / end_time).
get_statisticsGet long-term aggregated statistics (mean/min/max per bucket) for an entity over the last N hours, including data older than the recorder's short-term retention window.
get_statistics_rangeGet long-term aggregated statistics for an entity over an explicit date/time range, useful for monthly/yearly trend queries.
get_error_logGet the Home Assistant error log, with optional level / integration / search_term / lines filters applied server-side.
get_entities_by_areaList entities in a specific area / room.
When to use it
- Check or control device states by voice/chat, e.g. 'Turn off all the lights in the kitchen' or 'What's the temperature in the master bedroom?'
- Create and debug Home Assistant automations through guided prompts
- Audit and summarize your smart home — list entities by area, summarize climate entities, or standardize entity naming
- Troubleshoot integrations and entities, e.g. review recent ERROR log lines or investigate why a motion-sensor automation isn't firing
- Analyze long-term trends such as power usage by day over the last month using long-term statistics
Security notes
Requires a Home Assistant Long-Lived Access Token (HA_TOKEN), which grants full control over the configured Home Assistant instance — store it securely. The optional HTTP transport exposes full Home Assistant control to anyone who can reach the port; it ships no built-in auth, so it must be placed behind a reverse proxy with auth, a VPN/zero-trust network, or bound to localhost only. The server binds 127.0.0.1 by default; never expose port 8000 to the open internet without auth. TLS verification cannot be disabled; for private CAs, install the CA root or set SSL_CERT_FILE.
Hass-MCP FAQ
How do I authenticate the server with Home Assistant?
Provide a Home Assistant Long-Lived Access Token via the HA_TOKEN environment variable, along with HA_URL pointing at your instance. Generate the token from your Home Assistant user profile.
Can I run it without Docker?
Yes. With Python 3.13+ and uv installed, you can run it via uvx by setting the command to 'uvx' with args ['hass-mcp'] and the same HA_URL / HA_TOKEN env vars.
What is the HTTP transport for, and is it safe to expose?
The streamable HTTP transport is for deployments that can't use stdio (MCP gateways, Smithery/PaaS hosting, or shared/network clients like LibreChat or OpenWebUI). It exposes full Home Assistant control with no built-in auth, so you must put it behind a reverse proxy with auth, a VPN/zero-trust network, or bind it to localhost only. Never expose port 8000 to the open internet without auth.
What URL should HA_URL use when Home Assistant runs on the same machine?
With Docker Desktop on Mac/Windows, use http://host.docker.internal:8123. If Home Assistant runs on another machine, use its actual IP or hostname. You may also need '--network host' when running Home Assistant in Docker on the same host.
Alternatives to Hass-MCP
Compare all alternatives →
AI-powered task-management system for AI-driven development that drops into Cursor, Windsurf, Claude Code, and more.
Background computer-use MCP server that drives native macOS, Windows, and Linux desktop apps without stealing focus.
Self-hosted MCP server for Jira and Confluence Cloud and Server/Data Center.