# Add to your Claude Code skills
git clone https://github.com/voska/hass-mcpNo comments yet. Be the first to share your thoughts!
A Model Context Protocol (MCP) server for Home Assistant integration with Claude and other LLMs.
Hass-MCP enables AI assistants like Claude to interact directly with your Home Assistant instance, allowing them to:
Pull the Docker image:
docker pull voska/hass-mcp:latest
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:
{
"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"
}
}
}
}
d. Replace YOUR_LONG_LIVED_TOKEN with your actual Home Assistant long-lived access token
e. Update the HA_URL:
http://host.docker.internal:8123 (Docker Desktop on Mac/Windows)f. Save the file and restart Claude Desktop
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 hostto the Docker args for the container to access Home Assistant. Alternatively, use the IP address of your machine instead ofhost.docker.internal.
Install uv on your system.
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:
{
"mcpServers": {
"hass-mcp": {
"command": "uvx",
"args": ["hass-mcp"],
"env": {
"HA_URL": "http://homeassistant.local:8123",
"HA_TOKEN": "YOUR_LONG_LIVED_TOKEN"
}
}
}
}
d. Replace YOUR_LONG_LIVED_TOKEN with your actual Home Assistant long-lived access token
e. Update the HA_URL:
http://host.docker.internal:8123 (Docker Desktop on Mac/Windows)f. Save the file and restart Claude Desktop
The "Hass-MCP" tool should now appear in your Claude Desktop tools menu
Hass-MCPcommanddocker run -i --rm -e HA_URL=http://homeassistant.local:8123 -e HA_TOKEN=YOUR_LONG_LIVED_TOKEN voska/hass-mcp
YOUR_LONG_LIVED_TOKEN with your actual Home Assistant tokenTo use with Claude Code CLI, you can add the MCP server directly using the mcp add command:
Using Docker (recommended):
claude mcp add hass-mcp -e HA_URL=http://homeassistant.local:8123 -e HA_TOKEN=YOUR_LONG_LIVED_TOKEN -- docker run -i --rm -e HA_URL -e HA_TOKEN voska/hass-mcp
Replace YOUR_LONG_LIVED_TOKEN with your actual Home Assistant token and update the HA_URL to match your Home Assistant instance address.
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.
[!CAUTION] HTTP mode exposes full Home Assistant control over the network. Anyone who can reach the port can call any tool — turn off lights, unlock doors, trigger automations, restart HA. The MCP spec does not yet ship a built-in auth layer in this server. Until it does, you must put it behind one of:
- A reverse proxy (nginx, Caddy, Traefik) doing basic-auth or bearer-token validation
- A VPN or zero-trust network (Tailscale, WireGuard, Cloudflare Access)
- Localhost binding only (the default — change
--hostonly if you know what you're doing)Do not expose
:8000to the open internet without auth.
Using uvx:
HA_URL=http://homeassistant.local:8123 \
HA_TOKEN=YOUR_LONG_LIVED_TOKEN \
uvx hass-mcp --http --port 8000
The server binds 127.0.0.1 by default. Override with --host 0.0.0.0 only when you've also configured auth in front of it.
docker run --rm -p 8000:8000 \
-e HA_URL=http://homeassistant.local:8123 \
-e HA_TOKEN=YOUR_LONG_LIVED_TOKEN \
voska/hass-mcp:latest --http --host 0.0.0.0 --port 8000
--host 0.0.0.0 is required inside Docker so the port is reachable through the bridge. Bind the publish (-p) to 127.0.0.1:8000:8000 if you only want it reachable from the host, or put a reverse proxy in front.
The MCP endpoint is at /mcp. Point your client at http://<host>:<port>/mcp.
The server honors the PORT environment variable (Smithery's convention) in addition to MCP_PORT. Smithery deployment requires --http mode and reads PORT automatically.
If your Home Assistant instance serves a certificate signed by your own CA (step-ca, smallstep, homelab OpenSSL), hass-mcp can verify it without disabling TLS:
update-ca-certificates on Linux). hass-mcp picks it up automatically via truststore.SSL_CERT_FILE at it.docker run --rm \
-v /path/to/your-ca.crt:/etc/ssl/certs/your-ca.crt:ro \
-e SSL_CERT_FILE=/etc/ssl/certs/your-ca.crt \
-e HA_URL=https://homeassistant.example.internal:8123 \
-e HA_TOKEN=YOUR_LONG_LIVED_TOKEN \
voska/hass-mcp:latest
SSL_CERT_FILE always takes precedence over the OS store when set. verify=False is intentionally not supported — use HA_URL=http://... if you genuinely want unencrypted local LAN traffic.
Here are some examples of prompts you can use with Claude once Hass-MCP is set up:
Hass-MCP provides several tools for interacting with Home Assistant:
get_version: Get the Home Assistant versionget_entity: Get the state of a specific entity with optional field filteringentity_action: Perform actions on entities (turn on, off, toggle)list_entities: Get a list of entities with optional domain filtering and searchsearch_entities_tool: Search for entities matching a querydomain_summary_tool: Get a summary of a domain's entitieslist_automations: Get a list of all automationscall_service_tool: Call any Home Assistant servicerestart_ha: Restart Home Assistantget_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 (start_time / end_time, ISO-8601)get_statistics: Get long-term aggregated statistics (mean / min / max
per bucket) for an e