Home Assistant MCP
A Home Assistant Custom Component that provides an MCP (Model Context Protocol) server using HTTP transport, allowing AI assistants like Claude to interact with your Home Assistant instance over HTTP
What is Home Assistant MCP?
Home Assistant MCP is a Model Context Protocol (MCP) server that allows AI assistants like Claude, Cursor, and VS Code to home assistant custom component that provides an mcp (model context protocol) server using http transport, allowing ai assistants like claude to interact with your home assistant instance over http
A Home Assistant Custom Component that provides an MCP (Model Context Protocol) server using HTTP transport, allowing AI assistants like Claude to interact with your Home Assistant instance over HTTP
This server falls under the Cloud Services and APIs categories on MCPgee, the world's largest MCP server directory with 33,000+ servers.
Features
- A Home Assistant Custom Component that provides an MCP (Mode
Use Cases
Maintainer
Works with
Installation
Manual Installation
npx hassConfiguration
Configuration Details
claude_desktop_config.json
Performance
Response Metrics
Resource Usage
How to Set Up and Use Home Assistant MCP
The hass-mcp server is a Home Assistant custom component that exposes an MCP (Model Context Protocol) server over HTTP transport, allowing AI assistants like Claude to query and control your Home Assistant smart home instance through natural language. It provides three core tools: retrieving the state of any entity, listing all available states, and calling any Home Assistant service to control devices. Smart home enthusiasts use it to ask their AI assistant to turn on lights, check sensor values, or trigger automations without writing scripts or using the HA dashboard.
Prerequisites
- A running Home Assistant instance (any recent version with custom component support)
- HACS (Home Assistant Community Store) installed for easy component installation
- HASS_URL: the HTTP(S) URL of your Home Assistant instance (e.g. http://homeassistant.local:8123)
- HASS_TOKEN: a long-lived access token generated from your Home Assistant user profile
- An MCP-compatible client such as Claude Desktop that supports HTTP transport
Install the custom component via HACS
Open HACS in your Home Assistant UI, go to Integrations, and search for 'hass-mcp'. Install it and restart Home Assistant. Alternatively, clone the repository manually into your custom_components directory.
# Manual installation (if not using HACS)
git clone https://github.com/TheWhykiki/hass-mcp.git
cp -r hass-mcp/custom_components/hass_mcp /config/custom_components/Generate a long-lived access token
In Home Assistant, click your username at the bottom of the sidebar, scroll to the bottom of your profile page, and create a long-lived access token. Copy and store it securely — it will not be shown again.
Enable the integration
After restarting Home Assistant with the component installed, go to Settings > Integrations and add the hass-mcp integration. It will start an HTTP MCP server on your Home Assistant instance.
Configure your MCP client
Add the Home Assistant MCP server to your Claude Desktop or other MCP client configuration, providing your Home Assistant URL and long-lived access token.
{
"mcpServers": {
"homeassistant": {
"command": "npx",
"args": ["hass"],
"env": {
"HASS_URL": "http://homeassistant.local:8123",
"HASS_TOKEN": "your_long_lived_access_token"
}
}
}
}Test the connection
Ask your AI assistant to list all Home Assistant states or get the state of a specific entity like 'light.living_room'. A successful response means the connection is working.
Home Assistant MCP Examples
Client configuration
Claude Desktop configuration connecting to a local Home Assistant instance using a long-lived access token.
{
"mcpServers": {
"homeassistant": {
"command": "npx",
"args": ["hass"],
"env": {
"HASS_URL": "http://homeassistant.local:8123",
"HASS_TOKEN": "your_long_lived_access_token_here"
}
}
}
}Prompts to try
Example prompts for controlling and querying your Home Assistant smart home through Claude.
- "What is the current state of light.living_room?"
- "List all entities in my Home Assistant and their current states"
- "Turn on the kitchen lights"
- "Set the thermostat to 72 degrees"
- "What is the temperature reading from sensor.outdoor_temperature?"
- "Call the script.good_morning service to run my morning routine"Troubleshooting Home Assistant MCP
Connection refused or cannot reach Home Assistant URL
Ensure HASS_URL is correct and reachable from the machine running the MCP client. If Home Assistant is on a different network or behind a VPN, the MCP client must be on the same network or have appropriate routing. Use the full URL including port (e.g. http://192.168.1.100:8123).
Authentication errors with 401 Unauthorized responses
Regenerate your long-lived access token in Home Assistant (user profile > Long-lived access tokens). Ensure the full token string is copied without extra spaces and update HASS_TOKEN in your configuration.
ha_list_states returns too much data and overwhelms the AI context
Use ha_get_state for specific entities instead of listing all states at once. Filter your queries to specific entity types (e.g., 'get the state of all lights') to reduce the data volume returned.
Frequently Asked Questions about Home Assistant MCP
What is Home Assistant MCP?
Home Assistant MCP is a Model Context Protocol (MCP) server that home assistant custom component that provides an mcp (model context protocol) server using http transport, allowing ai assistants like claude to interact with your home assistant instance over http It connects AI assistants to external tools and data sources through a standardized interface.
How do I install Home Assistant MCP?
Follow the installation instructions on the Home Assistant MCP GitHub repository. Clone the repo, install dependencies, and add the server config to your AI client.
Which AI clients work with Home Assistant MCP?
Home Assistant MCP works with all major MCP-compatible AI clients including Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot), Windsurf, and Cline.
Is Home Assistant MCP free to use?
Yes, Home Assistant MCP is open source and available under the MIT License license. You can use it freely in both personal and commercial projects.
Home Assistant MCP Alternatives — Similar Cloud Services Servers
Looking for alternatives to Home Assistant MCP? 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 MCP 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 MCP?
Browse our complete directory of 33,000+ MCP servers, read setup guides for your editor, and start building with the Model Context Protocol.