Home Assistant

Home Assistant MCP server

Read your Home Assistant's entities, areas, history and logbook from your AI assistant, ask it anything a template can answer, and run its actions: dim a light, set a thermostat, start a script. Running an action is the only thing that changes anything, and actions on locks, alarm panels, covers and valves are approved by you, call by call, before they run. Nothing here moves money.

You need a Home Assistant this machine can reach (on your network or through its remote address) and a long-lived access token. A token of a user who is not an administrator is the recommended choice: every tool works with it except render_template, and the server refuses by itself, without asking Home Assistant, the few actions Home Assistant keeps for administrators (reloads, restarts and the like). An administrator's token adds those. There is no account to open and no cost. A wrong token costs a failed login, and Home Assistant may ban an address after a few, so the server never sends a refused token twice.

What you can ask

• "Which lights are on right now?"
• "How did the living room temperature change overnight?"
• "Who or what unlocked the front door this morning?"
• "Which devices are in the hallway?"
• "Dim the kitchen light to 30 percent."
• "Lock the front door." (you approve it first)

Install

.%22%7D%5D&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40foreverworks%2Fmcp-home-assistant%22%5D%2C%22env%22%3A%7B%22HOME_ASSISTANT_URL%22%3A%22%24%7Binput%3Ahome_assistant_url%7D%22%2C%22HOME_ASSISTANT_TOKEN_FILE%22%3A%22%24%7Binput%3Ahome_assistant_token_file%7D%22%2C%22HOME_ASSISTANT_CONFIRM_DOMAINS%22%3A%22%24%7Binput%3Ahome_assistant_confirm_domains%7D%22%7D%7D)

With Claude Code:

claude mcp add home-assistant -e HOME_ASSISTANT_URL="<Home Assistant address>" -e HOME_ASSISTANT_TOKEN_FILE="<path to Long-lived access token file>" -- npx -y @foreverworks/mcp-home-assistant

Claude Desktop (Settings, Developer, Edit Config) and most other clients read the same command as JSON:

{

"mcpServers": { "home-assistant": { "command": "npx", "args": ["-y", "@foreverworks/mcp-home-assistant"], "env": { "HOME_ASSISTANT_URL": " ", "HOME_ASSISTANT_TOKEN_FILE": " " } } } }

Each runs the published package on Node 22.19 or newer. VS Code and the Claude Desktop bundle ask for each setting as they add the server; leave an optional one empty. Cursor reads each from your environment instead (${env:HOME_ASSISTANT_URL} and so on), so set them before you start Cursor. The commands above set only what is required; Configuration has the rest.

From a clone

git clone https://github.com/foreverworks/mcps.git && cd mcps

npm ci && npm run build claude mcp add home-assistant -e HOME_ASSISTANT_URL=" " -e HOME_ASSISTANT_TOKEN_FILE=" " -- node "$PWD/servers/home-assistant/dist/index.js"

In a JSON configuration, the command is node and its one argument the full path of servers/home-assistant/dist/index.js. To share one running copy between several clients over HTTP, see docs/deploying.md.

Configuration

Every call reads these again, so a corrected value takes effect on the next call without a restart. With them unset the server still starts and lists its tools, and each tool answers a config error naming what is missing.

A deployment that sets MCP_EGRESS_ALLOW must allow the host of HOME_ASSISTANT_URL (homeassistant.local for the address above): the server reaches nothing else, over HTTP or its WebSocket. A sandbox that closes private networks (systemd's IPAddressDeny) must open the instance's address (docs/deploying.md). The variables every server shares are in docs/configuration.md.

Getting a long-lived access token

1. Make a person for the assistant in Settings, People, let it log in, and leave Administrator off; then sign in as that user. The logbook then names it as the cause of what it does, and it can do everything in your home's entities but change Home Assistant itself. Use an administrator only if you want render_template and the admin-only actions: Home Assistant answers anyone else's request for those with a 401 that it counts as a failed login, which is why this server learns whose token it holds and never sends them one.
2. Open your profile (your name at the bottom of the sidebar) and its Security tab.
3. Under Long-lived access tokens, select Create token, give it a name such as "MCP server", and copy the token. Home Assistant shows it once; it is valid for ten years unless you delete it there.
4. Save it alone in a file only you can read, and point HOME_ASSISTANT_TOKEN_FILE at it:

   umask 077 && printf '%s\n' '<the token>' > home-assistant-token

First run

1. Ask for health. A good answer says ok: true, the version, state: RUNNING, the time zone, websocket: ok, the token's user and whether it is an administrator (if not, unavailable_tools lists render_template), and how many entities each domain has.
2. Ask what is in an area, or which lights are on, to see list_areas and list_entities at work, then try an action on a light.
3. If health answers auth, fix the token before anything else: see Troubleshooting.

Tools

read changes nothing; write runs an action in your home; write in bold is approved by you before every call (below).

Confirmation

call_action refuses, with needs_confirmation and before sending anything, an action that needs your approval:

• an action in one of HOME_ASSISTANT_CONFIRM_DOMAINS (lock.unlock, cover.open_cover, alarm_control_panel.alarm_disarm, valve.open_valve);
• an action of another domain aimed at an entity of one (homeassistant.toggle on cover.garage_door);
• a homeassistant action aimed at devices, areas, floors, labels or all, which can reach any of them.

Those go through call_action_confirmed, which is confirmed like a payment, though nothing is paid: your client asks you before each call (Claude Code does, in every permission mode). With MCP_CONFIRM=elicit the server asks you itself, in one line computed from the call that will run, a code or a password shown as ****:

home-assistant: run the Home Assistant action lock.unlock on lock.front_door, with code=****

MCP_MAX_ACCESS=read turns both action tools off and leaves every read. How each client asks is in docs/security.md.

Troubleshooting

`auth`, status 401. Home Assistant refused the token: it was deleted, its user was removed or deactivated, or it was copied short. Make a new one (above) and put it in the token file. Until the file holds another token or the server restarts, every call answers auth with sent: false and sends nothing, because Home Assistant logs each refusal as a failed login and can ban the address.

`auth`, status 403. Home Assistant, or a proxy in front of it, refuses this machine's address. Usually Home Assistant banned it after failed logins: remove the address from ip_bans.yaml in Home Assistant's configuration folder, restart Home Assistant, check the token, then restart this server.

`unreachable`. Nothing answered at HOME_ASSISTANT_URL. Check that Home Assistant runs and that this machine reaches it: a browser here should open the same address. The message names what the network said (ECONNREFUSED: nothing listens on that port; ENOTFOUND: the name