homeassistant-mcp
A Node.js MCP server through which an agent controls Home Assistant devices and edits its automations
- 576 ★ on the repository
- Last commit
- Apache-2.0
Broad access
Why this level
- The Home Assistant token opens control of locks, cameras, climate and every other device in the house
- The tools install and remove add-ons and HACS packages and change automations in the working configuration
- The HTTP interface on port 3000 exposes home control to network clients until you restrict access to the port
Install
- Works in
Manual install
git clone https://github.com/tevonsb/homeassistant-mcp.git && cd homeassistant-mcp && cp .env.example .env && docker compose up -dThe recommended way through Docker Compose. Before starting, put the Home Assistant address and token into .env. Check: http://localhost:3000/health.
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The Home Assistant token opens control of locks, cameras, climate and every other device in the house
- The tools install and remove add-ons and HACS packages and change automations in the working configuration
- The HTTP interface on port 3000 exposes home control to network clients until you restrict access to the port
This is third-party code. Review the repository files before installing.
What it does
The server links your Home Assistant instance to an agent over MCP. From a plain-language request the agent turns lights on, changes their brightness and color, sets temperature and climate mode, and moves covers. It also operates locks, vacuums and media players, and reads sensor and camera states. Separate tools work with the system itself. `addon` installs and removes add-ons, starts and restarts them. `package` installs integrations, themes and Python scripts from the HACS catalog, as well as AppDaemon and NetDaemon apps. `automation_config` creates, edits and duplicates automations with triggers, conditions and actions. Next to MCP the server runs an HTTP interface with token checks and request rate limits.
Who it is for. For Home Assistant owners who want to run their home and system settings through Claude Desktop or another MCP client.
Good fit when
- You want to tell an agent to set the living-room light to half brightness and see the command carried out
- You want the agent to build an automation, for example a light driven by a motion sensor, with a trigger, conditions and actions
- You need to watch device state changes live through an event stream
- Your devices are grouped by rooms and floors and you want to address them by those groups
Not a fit when
- You do not run Home Assistant: the server speaks only to its API and handles no other smart-home system
- The Home Assistant token is stored carelessly or the instance is open to the internet: a leaked token gives outsiders full access to your home through the server
- You want to test an automation in isolation without risk to real devices: the tool changes the working configuration
Example request
Turn the living-room light on at 50 percent brightness and create an automation that switches on the hallway light when the hallway motion sensor fires.MCP
- Transport
- stdio, http, sse
- Authentication
- API key
Environment variables
HASS_HOSTrequired- Address of the Home Assistant instance, for example http://homeassistant.local:8123.
HASS_TOKENrequired, secret- A long-lived Home Assistant access token.
HASS_SOCKET_URLrequired- Home Assistant WebSocket address, for example ws://homeassistant.local:8123/api/websocket.
PORT- Port of the HTTP server, 3000 by default.
DEBUG- Debug mode, true or false.
Limitations
You need Node.js 20.10.0 or newer, a running Home Assistant and a long-lived access token. Managing add-ons needs Supervisor access, and packages need HACS installed. The Docker variant runs the server as a separate service, and it does not work inside Claude Desktop. The author documents a WebSocket channel for real-time updates, yet the project status lists it as unfinished. Stronger security and wider test coverage are in progress too. The last commit was made in January 2026.
How to disable. Stop the containers with `docker compose down` or remove the `homeassistant` block from the Claude Desktop config. Then revoke the long-lived token in your Home Assistant user profile: while the token is valid, any running server that holds it keeps access to your home.
FAQ
How do I connect homeassistant-mcp to Claude Desktop?
Build the project with `npm install` and `npm run build`. Then add a `homeassistant` block to the client config with the `node` command, the path of the built `dist` folder and the variables `HASS_HOST`, `HASS_TOKEN` and `HASS_SOCKET_URL`.
Where do I get a token for Home Assistant?
You create a long-lived token in your Home Assistant user profile and put it into the `HASS_TOKEN` variable of the `.env` file. Make a dedicated token for the server, so you can revoke it without touching other integrations.
Can I receive device events in real time?
Yes. The server publishes a Server-Sent Events stream at `/subscribe_events` with the token as a parameter and a filter by domain or device, for example `domain=light`. The event format is covered in `docs/SSE_API.md`.
What are the rate limits?
Regular endpoints accept 100 requests per minute per IP address. Over the limit the server returns a `RATE_LIMIT_EXCEEDED` error with the reset time.
What should I do about the `toSorted is not a function` error?
Update Node.js, for example with `nvm install 20.10.0` and `nvm use 20.10.0`. Earlier versions do not support this method.
Discussion
No questions or reviews yet.
Related
MCP serversAn MCP server for Home Assistant: the agent reads smart-home state and controls devices through your instance
MCP server for Home Assistant: an agent reads device states, controls them and edits smart home dashboards
Home Assistant Vibecode Agent
home-assistant-vibecode-agent
A Home Assistant add-on and MCP server: an agent checks the configuration and applies automations. A long-lived token is needed. Not an official project
An MCP server for driving Windows: the agent opens apps, clicks and types, reads window and UI state, and works with files and PowerShell
An MCP server for macOS: the agent moves the mouse, types, manages windows and captures the screen when an app has no API
MCP server for AppleScript: the agent runs scripts and controls Mac apps, from Notes and Calendar to files
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| homeassistant-mcp (this entry) | no | API key | 576 | |
| ha-mcp | no | API key | 5,333 | an MCP server that reads home state through your Home Assistant instance, while this one adds add-on and HACS package management |
| Hass-MCP | no | API key | 351 | a Python MCP server that reads device states, controls them and edits dashboards |
| Home Assistant Vibecode Agent | no | API key | 647 | a Home Assistant add-on where the agent checks configuration and applies automations |
README in short
The project page opens with a list of devices and features, then walks through installation with Docker or from source and the environment variables. Most of it is a tool reference with sample requests. The end covers common errors, limits and work status.