Home Assistant
A Model Context Protocol server that enables AI assistants like Claude to interact directly with Home Assistant, allowing them to query device states, control smart home entities, and perform automation tasks.
What is Home Assistant?
Home Assistant is a Model Context Protocol (MCP) server that allows AI assistants like Claude, Cursor, and VS Code to model context protocol server that enables ai assistants like claude to interact directly with home assistant, allowing them to query device states, control smart home entities, and perform automation...
A Model Context Protocol server that enables AI assistants like Claude to interact directly with Home Assistant, allowing them to query device states, control smart home entities, and perform automation tasks.
This server falls under the Cloud Services category on MCPgee, the world's largest MCP server directory with 33,000+ servers.
Features
- A Model Context Protocol server that enables AI assistants l
Use Cases
Maintainer
Works with
Installation
Manual Installation
npx hass-mcpConfiguration
Configuration Details
claude_desktop_config.json
Performance
Response Metrics
Resource Usage
How to Set Up and Use Home Assistant
Hass-MCP is a Python MCP server that gives Claude and other AI assistants direct, bidirectional access to a Home Assistant instance. Claude can query the real-time state of any device or sensor, control lights and switches, list and trigger automations, search entities by name or type, and get domain-level summaries of your smart home — all through natural-language conversation. The server is designed for token efficiency with lean JSON responses, and supports both Docker and uvx deployment alongside streamable HTTP transport for multi-client scenarios.
Prerequisites
- A running Home Assistant instance (local or cloud) with a Long-Lived Access Token
- Docker (recommended) or Python 3.13+ with uv installed for the uvx path
- The Home Assistant URL (e.g., http://homeassistant.local:8123 or an IP address)
- Claude Desktop, Claude Code CLI, or Cursor as your MCP client
- HA_URL and HA_TOKEN environment variables with your instance URL and token
Generate a Home Assistant Long-Lived Access Token
In Home Assistant, go to your Profile page (click your username in the sidebar), scroll to the bottom, and create a Long-Lived Access Token. Copy it — you will not be able to see it again.
Pull the Docker image (recommended path)
Pull the official voska/hass-mcp Docker image. This is the recommended installation method as it avoids Python dependency management.
docker pull voska/hass-mcp:latestAdd the MCP server to Claude Desktop using Docker
Edit claude_desktop_config.json to add hass-mcp. Replace YOUR_LONG_LIVED_TOKEN with your actual token and update HA_URL to your Home Assistant address.
Alternative: use uvx instead of Docker
If you prefer not to use Docker, configure Claude Desktop to launch the server via uvx. Set HA_URL and HA_TOKEN in the env block.
Restart Claude Desktop and test
Restart Claude Desktop after saving the config. Ask Claude to list your lights or check the temperature in a room to verify the connection to Home Assistant is working.
Home Assistant Examples
Client configuration (Docker)
Add this block to claude_desktop_config.json. This is the Docker-based configuration recommended by the project.
{
"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"
}
}
}
}Client configuration (uvx)
Alternative configuration using uvx if Docker is not available.
{
"mcpServers": {
"hass-mcp": {
"command": "uvx",
"args": ["hass-mcp"],
"env": {
"HA_URL": "http://homeassistant.local:8123",
"HA_TOKEN": "YOUR_LONG_LIVED_TOKEN"
}
}
}
}Prompts to try
Use these prompts in Claude to interact with your Home Assistant smart home.
- "What lights are currently on in my home?"
- "Turn off all the lights in the living room"
- "What is the current temperature on my thermostat?"
- "List all my automations and tell me which ones are enabled"
- "Find all entities with 'bedroom' in their name and show their current states"
- "Give me a summary of all my smart home devices by domain"Troubleshooting Home Assistant
Claude cannot reach Home Assistant — connection refused or timeout
If Home Assistant runs on the same machine as Docker, use 'http://host.docker.internal:8123' instead of 'localhost'. On Linux you may need to add '--network host' to the Docker args. If on a different machine, use the actual IP address rather than a hostname.
HA_TOKEN authentication fails with 401 Unauthorized
Verify the token was copied completely — long-lived tokens are very long strings. Generate a new token in Home Assistant Profile > Long-Lived Access Tokens if unsure. Also confirm HA_URL points to the correct port (default 8123).
Docker container exits immediately when Claude Desktop tries to start it
The container must receive stdin from Claude Desktop to stay alive (the -i flag is critical). Verify the args array in your config includes '-i'. Also check Docker is running before starting Claude Desktop.
Frequently Asked Questions about Home Assistant
What is Home Assistant?
Home Assistant is a Model Context Protocol (MCP) server that model context protocol server that enables ai assistants like claude to interact directly with home assistant, allowing them to query device states, control smart home entities, and perform automation tasks. It connects AI assistants to external tools and data sources through a standardized interface.
How do I install Home Assistant?
Follow the installation instructions on the Home Assistant GitHub repository. Clone the repo, install dependencies, and add the server config to your AI client.
Which AI clients work with Home Assistant?
Home Assistant works with all major MCP-compatible AI clients including Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot), Windsurf, and Cline.
Is Home Assistant free to use?
Yes, Home Assistant is open source and available under the MIT License license. You can use it freely in both personal and commercial projects.
Home Assistant Alternatives — Similar Cloud Services Servers
Looking for alternatives to Home Assistant? Here are other popular cloud services servers you can use with Claude, Cursor, and VS Code.
Open WebUI
★ 138.2kUser-friendly AI Interface (Supports Ollama, OpenAI API, ...)
Anything LLM
★ 60.4kThe all-in-one AI productivity accelerator. On device and privacy first with no annoying setup or configuration.
LocalAI
★ 46.4kLocalAI is the open-source AI engine. Run any model - LLMs, vision, voice, image, video - on any hardware. No GPU required.
Nacos
★ 33.0kan easy-to-use dynamic service discovery, configuration and service management platform for building AI cloud native applications.
Xiaozhi ESP32
★ 26.7k本项目为xiaozhi-esp32提供后端服务，帮助您快速搭建ESP32设备控制服务器。Backend service for xiaozhi-esp32, helps you quickly build an ESP32 device control server.
Gateway
★ 11.8kA blazing fast AI Gateway with integrated guardrails. Route to 1,600+ LLMs, 50+ AI Guardrails with 1 fast & friendly API.
Browse More Cloud Services MCP Servers
Explore all cloud services servers available in the MCPgee directory. Each server includes setup guides for Claude, Cursor, and VS Code.
Set Up Home Assistant in Your Editor
Choose your AI client for step-by-step setup instructions.
Quick Config Preview
Add this to your claude_desktop_config.json or .cursor/mcp.json
Ready to use Home Assistant?
Browse our complete directory of 33,000+ MCP servers, read setup guides for your editor, and start building with the Model Context Protocol.