Best for
- Home Assistant users who want natural language control of their smart home
- Developers who enjoy using AI assistants like Claude
- Users who need quick troubleshooting of automations and entities
H
Hass MCP Server
Community
Control and query Home Assistant from Claude and other LLMs — a Model Context Protocol (MCP) server.
GitHub source repository ↗
52FMRS · D
Hass-MCP is feature-rich, covering entity management, automations, history, logs, and more, with token efficiency. However, security risks are prominent, especially in HTTP mode, which requires strict protection. It suits users who want AI control of their home, but careful permission and network configuration is needed.
Hass-MCP is a Model Context Protocol (MCP) server for integrating Home Assistant with Claude and other large language models. It lets AI assistants directly read device states, control lights and switches, get smart home summaries, troubleshoot automations, and search entities, with lean JSON responses to minimize token usage.
Tools
get_version
Get the Home Assistant version.
get_entity
Get the state of a specific entity with optional field filtering.
entity_action
Perform actions on entities (turn on, off, toggle).
list_entities
Get a list of entities with optional domain filtering and search.
search_entities_tool
Search for entities matching a query.
domain_summary_tool
Get a summary of a domain's entities.
list_automations
Get a list of all automations.
call_service_tool
Call any Home Assistant service.
restart_ha
Restart Home Assistant.
get_history
Get the state history of an entity (last N hours).
get_history_range
Get state-change history for an entity over an explicit date/time range.
get_statistics
Get long-term aggregated statistics (mean/min/max per bucket) for an entity over the last N hours.
get_statistics_range
Get long-term statistics for an explicit date/time range, useful for monthly/yearly trends.
get_error_log
Get the Home Assistant error log with optional server-side filters.
get_entities_by_area
List entities in a specific area or room.
Setup
- Have a Home Assistant instance with a Long-Lived Access Token.
- Install via Docker (recommended) or Python/uv.
- Add the MCP server to Claude Desktop (or Cursor, Claude Code).
- Set environment variables HA_URL and HA_TOKEN.
- Restart the client.
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"
}
}
}
}
Fit and risk
Not for
- Users who do not need AI control
- Those who cannot manage long-lived tokens or network configuration
- Those who need offline or fully local environments without exposing server ports (especially in HTTP mode)
Required permissions
- Requires a Home Assistant Long-Lived Access Token (HA_TOKEN)
- Needs network access to the Home Assistant instance via HA_URL
- In HTTP mode, opens a port that must be protected via proxy or VPN to prevent unauthorized access
Risks and side effects
- If HTTP mode is exposed to the public internet, anyone can control all smart devices (lights, locks, automations, restart HA)
- Token leakage could lead to full control of Home Assistant
- Wrong operations could cause device anomalies or unintended automations
Troubleshooting
- Check that HA_URL is reachable; inside Docker use host.docker.internal or the actual IP
- Ensure HA_TOKEN is valid and not expired
- If the Docker container cannot reach Home Assistant, try adding --network host or use the host IP
- Inspect client logs to see if the MCP server starts properly
- If using a custom CA certificate, set SSL_CERT_FILE to the CA file
- For HTTP mode, verify port binding and proxy configuration
Use cases
Ask about current living room light states
Turn off all kitchen lights
Check the temperature in the master bedroom
List all sensors containing temperature data
Create an automation that turns on lights at sunset
Troubleshoot a bedroom motion sensor automation
View error log entries from Home Assistant
Show daily power usage for the last month
Supported clients
Claude DesktopFull support
CursorFull support
Claude CodeFull support