# home-assistant-mcp

A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that lets
coding agents — Cursor, VS Code (Copilot), Claude Desktop and anything else that
speaks MCP — talk **directly** to [Home Assistant](https://www.home-assistant.io)
and (optionally) the [ESPHome](https://esphome.io) dashboard.

Instead of copy-pasting entity ids, YAML and current values into your agent, the
agent can discover entities, read live state, render templates, call services and
edit automations itself — and iterate until the code actually works.

[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)

![Claude Code asked to set two lights to 40% and switch a socket on; the dashboard pane beside it lights them up as the home reports the change.](docs/images/vome-dash.gif)

In Claude Code, four side panes show what Claude is doing to your home as it
happens: the automation it is working on, the ESPHome device it is building,
the home's health score and a dashboard that works. One command installs all
four ([below](#claude-code-the-side-panes)).

> Part of the [Vome](https://vome.io) family and an open-source companion to
> **VomeHome** (managed Home Assistant). It is useful stand-alone for any Home
> Assistant user.

---

## Why

A typical "change an automation" loop today looks like: you tell the agent which
entities exist, paste their current values, paste the YAML, apply the change, then
manually check whether it worked. With this server the agent does all of that:

- **See** — list entities/areas/devices, read exact states and attributes, pull
  history and the logbook.
- **Experiment** — render Jinja templates against live state, check configuration,
  read the error log.
- **Change** — call services, create/update/delete/trigger automations, and (for
  ESPHome) edit, validate, compile and flash device firmware.

All write operations are **off by default** and gated behind an explicit safety
policy (see [Safety](#safety)).

---

## Tools

### Home Assistant — read

| Tool | Description |
| --- | --- |
| `ha_get_config` | Core config: version, location, time zone, loaded components. |
| `ha_list_entities` | List entities (filter by domain, free-text search, area). |
| `ha_get_state` | Full state + attributes for one or more entities. |
| `ha_get_history` | Historical state changes over a time window. Given only a start time, it runs up to now (Home Assistant alone stops 24 hours after the start); `ha_get_logbook` does the same. |
| `ha_list_services` | Available services (and their fields for a given domain). |
| `ha_list_areas` | Areas (rooms/zones). |
| `ha_list_devices` | Device registry (filter by area / search). |
| `ha_get_entity_registry` | Registry metadata: platform, area, device, disabled/hidden. |
| `ha_render_template` | Render a Jinja2 template against live state. |
| `ha_list_helpers` | List stored helpers (input_boolean, input_number, counter, timer, …). |
| `ha_list_automations` | Automations with entity_id, unique id, state, last-triggered. |
| `ha_get_automation` | Full automation config (triggers/conditions/actions). |
| `ha_check_config` | Validate the configuration (Check configuration). |
| `ha_get_system_log` | **Deduplicated, structured errors** — level, logger, source, count, first/last seen. Start here. |
| `ha_get_error_log` | Tail of the raw Home Assistant error log. |
| `ha_get_supervisor_log` | Add-on / Core / Supervisor / host logs (HAOS or Supervised). |
| `ha_camera_image` | A camera's current still, as an image the agent can see. Via VomeHome the key needs Cameras ticked. |
| `ha_camera_frame` | A camera still decoded and shrunk to a small grid of RGB pixels, for clients that draw pictures in text. |
| `ha_view_snapshot` | Everything a dashboard view shows in one call: states, rendered templates, history in few points, camera frames. For dashboard clients. |
| `ha_watch_states` | Wait for state changes instead of polling: the home's Vome component sends them as they happen (through VomeHome). |
| `ha_get_logbook` | Human-readable logbook entries. |
| `ha_list_traces` | Recent automation/script runs and how each one stopped. |
| `ha_get_trace` | Step-by-step detail for one run, with `failed_at` naming the blocking step. |

### Home Assistant — write (write-gated)

> Write-gating depends on the mode. In **direct** mode the MCP is the only guard,
> so these refuse until `HA_ALLOW_WRITE=true`. In **brokered** mode your VomeHome
> API key carries the per-instance `ha:write` / `ha:config` scopes and the server
> enforces them, so the client flags are optional local-only restrictions.

| Tool | Description |
| --- | --- |
| `ha_call_service` | Call any service (turn_on, set_temperature, …). |
| `ha_clear_system_log` | Empty the structured error store (only needs `HA_ALLOW_WRITE`). |
| `ha_set_log_level` | Change logging for one integration at runtime (only needs `HA_ALLOW_WRITE`). |
| `ha_set_automation` | Create or update an automation (also needs `HA_ALLOW_CONFIG_WRITE`). |
| `ha_set_helper` | Create or update a helper — no `configuration.yaml`, no restart. |
| `ha_read_config_file` | Read a file under the config directory — text by default, or `encoding: 'base64'` for a binary asset (needs `ha:files`). |
| `ha_write_config_file` | Replace a file under the config directory — text by default, or `encoding: 'base64'` for a binary asset; checks the config and restores the file if it fails (needs `ha:files`). |
| `ha_delete_config_file` | Delete one file under the config directory. Never a directory, and never `configuration.yaml`, `secrets.yaml` or Home Assistant's database. Names its target home like a write (needs `ha:files`, and Vome add-on 0.3.55 / integration 0.9.39 on the home). |
| `ha_edit_config_file` | Change part of a text file in place: exact find-and-replace edits that must each match once, then the same check-and-restore as a write. For a three-line change to a large file (needs `ha:files`). |
| `ha_list_config_files` | List a directory under the config directory (needs `ha:files`). |
| `ha_delete_helper` | Delete a stored helper. Refuses when the id looks shared with a `configuration.yaml` helper, because Home Assistant would take that entity down with it. |
| `ha_delete_automation` | Delete an automation (also needs `HA_ALLOW_CONFIG_WRITE`). |
| `ha_get_script` / `ha_set_script` / `ha_delete_script` | Scripts by id, the same way as automations: put a step several automations share in one script. Writes need `HA_ALLOW_CONFIG_WRITE`. |
| `ha_update_entity` | Rename, re-id, move, re-icon, disable or hide an entity in the registry (needs `HA_ALLOW_CONFIG_WRITE`). |
| `ha_remove_entity` | Remove an orphaned registry entry (needs `HA_ALLOW_CONFIG_WRITE`). |
| `ha_matter_reinterview` | The Matter device page's Re-interview, for a device whose endpoints changed after a firmware update (needs `HA_ALLOW_CONFIG_WRITE`). |
| `ha_trigger_automation` | Manually run an automation now. |
| `ha_reload_automations` | Reload automations without restarting. |

### Lovelace dashboards (direct HA or VomeHome brokered)

| Tool | What it does |
|------|----------------|
| `ha_list_dashboards` | List dashboards (`url_path`, title, mode, sidebar). |
| `ha_get_dashboard` | Read one dashboard's full config (views, cards, …). |
| `ha_save_dashboard` | Save/replace a dashboard config (needs `HA_ALLOW_CONFIG_WRITE`). |
| `ha_create_dashboard` | Register a new storage-mode dashboard (needs `HA_ALLOW_CONFIG_WRITE`). |
| `ha_delete_dashboard` | Delete a dashboard by id (needs `HA_ALLOW_CONFIG_WRITE`). |

> Dashboards use Home Assistant's WebSocket API. In brokered mode VomeHome proxies
> an allowlisted subset via `POST /api/v1/instances/<id>/ha/ws/command`.
| `ha_fire_event` | Fire a custom event on the event bus. |

### ESPHome (brokered to a relay-connected HA)

| Tool | Description |
| --- | --- |
| `esphome_dashboard_info` | How ESPHome is reached, and whether flashing/logs are available right now. |
| `esphome_list_devices` | List dashboard configurations/devices; flags configs needing renames. |
| `esphome_list_migrations` | ESPHome spellings a config still uses that have been renamed. |
| `esphome_get_config` | Read a configuration's YAML. |
| `esphome_save_config` | Write a configuration's YAML, whole: for a new file (write-gated). |
| `esphome_edit_config` | Change part of a configuration in place with exact find-and-replace edits, so a long file is not resent (write-gated). |
| `vome_health_report` | Vome's health score for the home and every finding, with severity, evidence, a recommendation and the entities involved. |
| `vome_health_check` | Run a fresh health check, to re-score after fixes (write-gated). |
| `esphome_validate` | Validate a configuration. |
| `esphome_compile` | Compile firmware. |
| `esphome_upload` | Compile + flash a device over the air; validates first (write-gated). |
| `esphome_logs` | Read a device's live logs — boot, wifi, sensors, crashes. |
| `esphome_clean` | Delete cached build files after a stale-build compile failure (write-gated). |

There is **nothing to configure**. Every command — builds and logs included —
goes through the VomeHome relay, so ESPHome works wherever brokered Home
Assistant does, with no port to open.

There is also no second way in. The ESPHome add-on is host-networked with its web
port disabled, behind an ingress that admits only the Supervisor and localhost,
so the Vome component on the home is the only thing that can reach the dashboard
at all. A direct-dashboard mode existed once (`ESPHOME_DASHBOARD_URL`) and was
removed in 0.6.0: it spoke a protocol ESPHome has since deleted, and on a default
install it could not connect anyway.

### Node-RED (`NODERED_URL`)

[Node-RED](https://nodered.org) is the flow-based editor that ships as a Home
Assistant add-on. It is powerful but fiddly to edit by hand — so let the agent
read and write the flow JSON for you. Flows are stored as a JSON array of nodes
grouped into tabs; these tools work a tab at a time (safe) or on the whole
config (deliberate). Writes are gated behind the same switches as editing HA
automations (`HA_ALLOW_WRITE` + `HA_ALLOW_CONFIG_WRITE`).

| Tool | Description |
| --- | --- |
| `nodered_get_flows` | Get the full flow config (all tabs) plus the current revision. |
| `nodered_get_flow` | Get one flow (tab) and its nodes by id. |
| `nodered_list_nodes` | List installed node modules/types (the palette). |
| `nodered_create_flow` | Add a new tab without disturbing existing flows (write-gated). |
| `nodered_update_flow` | Replace one tab by id, leaving others untouched (write-gated). |
| `nodered_delete_flow` | Delete a tab and its nodes (write-gated). |
| `nodered_set_flows` | Replace the **entire** flow config and deploy (write-gated). |

### VomeHome (require `VOMEHOME_TOKEN`)

[VomeHome](https://vome.io) is managed Home Assistant hosting. Log in to the
portal with GitHub, mint a personal access token under **Account → API tokens**,
and the agent can manage your instances from the editor. Advanced management
stays behind a full browser login on the portal.

| Tool | Description |
| --- | --- |
| `vomehome_list_instances` | List your HA instances with status, tier, URL, live health, the **active** instance and per-instance client write/config access. |
| `vomehome_get_instance` | Details + live status for one instance. |
| `vomehome_use_instance` | Switch which instance the `ha_*` tools target (multi-instance — see [Several instances from one token](#several-instances-from-one-token)). |
| `vomehome_reboot_instance` | Reboot an instance's VM (write-gated). |
| `vomehome_create_instance` | Create a throwaway test/sandbox instance (needs the create scope on your API key; the creating key is granted full HA access on the new instance, which becomes the active target). |
| `vomehome_get_login_url` | Mint a one-click HA login URL to open in a new tab. |
| `vomehome_create_guest_link` | Create a non-admin HA user + one-click login URL for sharing (needs `HA_ALLOW_CONFIG_WRITE`). Vome-hosted instances only. |
| `vomehome_list_guest_links` | List guest links for an instance, revoked ones included. |
| `vomehome_revoke_guest_link` | Revoke a guest link immediately. |

**Guest links** are self-serve, revocable sharing: a non-admin (unless you
pass `admin: true`) Home Assistant account plus a one-click login URL, minted
and torn down on demand, without handing out the owner's own credentials.
They only work for **Vome-hosted** instances — minting a token for someone
other than the owner needs direct network access to the VM, which a
self-hosted/relay-linked instance doesn't offer the portal.

**Home Assistant's permission model is coarse.** A non-admin guest is locked
out of Settings and Developer Tools, but can still call services on *any*
entity the dashboard shows them — there is no per-entity guest scoping in
Home Assistant itself. A guest link is safe on a dedicated demo/sandbox
instance built to be poked at. It is not a substitute for real access control
on somebody's actual house — don't point one at one. The link auto-expires
(`expires_in`, default 24h, capped at 30 days — Home Assistant's own
long-lived tokens never expire on their own, so Vome enforces this) and can
be revoked early at any time.

### Integrations & config entries

| Tool | Description |
| --- | --- |
| `ha_list_config_entries` | List installed integrations (config entries). Optional domain filter. |
| `ha_delete_config_entry` | Delete a config entry by id — the fix for an orphaned/duplicate entry left behind after a device was removed, which is otherwise why a re-added device's entities pick up a `_2` suffix. Needs `HA_ALLOW_CONFIG_WRITE`. |
| `ha_list_discovery_flows` | List integrations Home Assistant has discovered on the network but not yet added. |
| `ha_config_flow` | Start (`handler`) or continue (`flow_id` + `user_input`) an integration's config flow. Needs `HA_ALLOW_CONFIG_WRITE`. |
| `ha_config_entry_options` | Read or set an integration's options — including ESPHome's `allow_service_calls`. |
| `ha_integration_setup_vome` | Add the Vome (`vomesync`) config entry with default settings, idempotently. |

### Supervisor / Vome add-on (HAOS / Supervised)

| Tool | Description |
| --- | --- |
| `ha_supervisor_api` | Call a Supervisor endpoint via `supervisor/api` (store, add-ons, …). |
| `ha_addon_install_vome` | Add `https://github.com/Vortitron/VomeSync` to the store, install **Vome**, and start it. |

### HACS (Home Assistant Community Store)

| Tool | Description |
| --- | --- |
| `ha_hacs_info` | HACS version, stage, and whether it has pending background tasks. |
| `ha_hacs_list_repositories` | List repositories HACS knows about (optionally filtered by category). |
| `ha_hacs_add_repository` | Add a custom repository by `owner/repo` and category. Confirms by re-listing, since HACS acks even a failed add. Needs `HA_ALLOW_CONFIG_WRITE`. |
| `ha_hacs_download_repository` | Install (or update) a tracked repository — the step that actually writes its files. Needs `HA_ALLOW_CONFIG_WRITE`. |
| `ha_hacs_remove_repository` | Uninstall a repository's files and stop tracking it. Needs `HA_ALLOW_CONFIG_WRITE`. |

There is no REST API or service call for managing HACS repositories — these
go over HACS's own WebSocket commands (`hacs/*`), the same way as the
Supervisor tools above. Adding a repository only registers it; call
`ha_hacs_download_repository` afterwards to install it, and restart Home
Assistant if it's a new integration or add-on domain.

### Users

| Tool | Description |
| --- | --- |
| `ha_list_users` | List every user: id, name, username, role, active/owner status. |
| `ha_create_user` | Create a user with a role (`admin` / `user` / `read_only`) but no login yet. Needs `HA_ALLOW_CONFIG_WRITE`. |
| `ha_update_user` | Change a user's name, role, active state, or local-only restriction. Needs `HA_ALLOW_CONFIG_WRITE`. |
| `ha_delete_user` | Permanently delete a user and its login. Needs `HA_ALLOW_CONFIG_WRITE`. |
| `ha_set_user_credentials` | Give a user with no login yet a username/password. Needs `HA_ALLOW_CONFIG_WRITE`. |
| `ha_change_user_password` | Reset the password for a user that already has a login. Needs `HA_ALLOW_CONFIG_WRITE`. |
| `ha_remove_user_credentials` | Remove a login without deleting the user. Needs `HA_ALLOW_CONFIG_WRITE`. |
| `ha_provision_service_login` | Give a program (an MQTT client, a Zigbee bridge, an ESPHome device) its own non-admin login and write the password straight into its add-on options or a secrets file. The password is generated here and never returned. Needs `HA_ALLOW_CONFIG_WRITE`, plus `ha:files` for secrets files. |

**A user + password these tools create is a standing Home Assistant login,
independent of any VomeHome API key.** Revoking the key that created it does
not remove the account — unlike everything else in this server, which acts
*through* the calling key and stops working the moment it's revoked. Treat
granting `ha:config` on an instance as equivalent to trusting the holder with
permanent account creation on that home. `role` has no default on
`ha_create_user`; it must be chosen explicitly rather than silently landing
on `admin`.

**Logins for programs: `ha_provision_service_login`.** Wiring a device into a
home usually stops at one step: someone invents a password and types it into
two places. `ha_set_user_credentials` makes the caller choose it, which an
agent should not be doing. This tool generates it instead (128 bits), writes it
into the consumer's add-on options (e.g. `mqtt.user` / `mqtt.password`) and/or a
secrets file, and replies with where it went, never what it is. The Mosquitto
add-on accepts Home Assistant logins, so one call wires an MQTT client. It
checks every target before creating anything, deletes a new login that could
be delivered nowhere, never makes an admin, is local-only by default, and with
`rotate=true` re-issues only logins it created itself (marked
`(service login)` in the user's name), never a person's account. Programs
outside Home Assistant, with neither add-on options nor a secrets file, are out
of its reach.

`ha_config_entry_options` reaches settings that exist nowhere else in the API.
The one people ask for is ESPHome's **"allow the device to perform Home
Assistant actions"** (`allow_service_calls`): a device cannot call HA services
without it, and it is several clicks deep in the UI, so it is routinely
forgotten. Get the entry id from `ha_list_config_entries` with `domain=esphome`,
call with `entry_id` alone to read the form, then again with `user_input`.
Submitting sets *every* field on the form, so send the values you read back with
only what you meant to change altered.

Needs a Supervised/HAOS target (e.g. a VomeHome sandbox from `vomehome_create_instance`, or the `ha-plc-sandbox` MCP entry). In brokered mode the API key's scopes decide — no `HA_ALLOW_WRITE` / `VOMEHOME_ALLOW_CREATE` env flags required. Container-only HA has no add-on store — use HACS for the integration there.

Typical developer flow: `vomehome_create_instance` → wait until running → `ha_addon_install_vome` → restart Core → add the Vome integration.

---

## Install

Requires **Node.js ≥ 18.18** (Node 20+ recommended). There is nothing to install
by hand — your editor launches the server on demand with `npx`, so the same
config works on every machine (no absolute paths).

### One‑click (Cursor)

[![Add to Cursor](https://img.shields.io/badge/Add%20to-Cursor-000?logo=cursor)](cursor://anysphere.cursor-deeplink/mcp/install?name=home-assistant&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkB2b3J0aXRyb24vaG9tZS1hc3Npc3RhbnQtbWNwIl0sImVudiI6eyJIQV9VUkwiOiJodHRwOi8vaG9tZWFzc2lzdGFudC5sb2NhbDo4MTIzIiwiSEFfVE9LRU4iOiJZT1VSX0hBX0xPTkdfTElWRURfVE9LRU4iLCJIQV9BTExPV19XUklURSI6ImZhbHNlIn19)

Click it, then edit the pre‑filled `HA_URL` and `HA_TOKEN`. (If the button does
nothing, copy the [`cursor://` link from the source of this section](#) into your
browser's address bar.)

### One‑line config

Add this to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one
project) and fill in your token — that's the whole install:

```json
{
	"mcpServers": {
		"home-assistant": {
			"command": "npx",
			"args": ["-y", "@vortitron/home-assistant-mcp"],
			"env": {
				"HA_URL": "http://homeassistant.local:8123",
				"HA_TOKEN": "paste-your-long-lived-token",
				"HA_ALLOW_WRITE": "false"
			}
		}
	}
}
```

### Verify / from source

```bash
npx -y @vortitron/home-assistant-mcp doctor   # one-off connectivity check

# or hack on it:
git clone https://github.com/Vortitron/home-assistant-mcp.git
cd home-assistant-mcp && npm install && npm run build
```

### LAN TCP tunnels (RDP, etc.)

```bash
npx -y @vortitron/home-assistant-mcp tunnel --token <jwt> --local-port 3390
```

Opens a local listener on `127.0.0.1:<local-port>` and forwards it, over the
same outbound relay Vome already uses (no port-forwarding on your router), to
a `tcp`-scheme LAN route on a Vome-linked Home Assistant — e.g. an RDP host.
Point `mstsc`/Remmina/any TCP client at that local address. Get a token from
Home Assistant: **Developer Tools → Actions → `vomesync.mint_lan_tcp_token`**
(or the Vome App's ingress panel → LAN tunnels → "Get tunnel token"). Tokens
are short-lived and scoped to one instance + one route.

---

## Configuration

Configuration is via environment variables (a local `.env` is also read). Copy
`.env.example` to `.env` and fill it in, or set the variables in your editor's MCP
config.

| Variable | Default | Description |
| --- | --- | --- |
| `HA_URL` | — (required) | Base URL, e.g. `http://homeassistant.local:8123`. |
| `HA_TOKEN` | — (required) | Long-lived access token (Profile → Security). |
| `HA_ALLOW_WRITE` | off (direct) / permissive (brokered) | Local write guard. In brokered mode the API key's per-instance scope decides (server-enforced); setting `false` only adds a local restriction. In direct mode this is the master switch and defaults off. |
| `HA_DENY_DOMAINS` | `lock,alarm_control_panel,cover,valve,camera` (direct) / empty (brokered) | Domains that can never be written. In brokered mode the API key's *Sensitive devices* setting decides, server-side; set this only to add a local restriction. |
| `HA_ALLOW_DOMAINS` | _(any)_ | If set, only these domains may be written. |
| `HA_ALLOW_CONFIG_WRITE` | off (direct) / permissive (brokered) | Local guard for editing automation config. Same semantics as `HA_ALLOW_WRITE`. |
| `NODERED_URL` | _(disabled)_ | Node-RED editor/admin base URL, e.g. `http://homeassistant.local:1880`. Enables the `nodered_*` tools. |
| `NODERED_TOKEN` | — | Bearer token if Node-RED `adminAuth` is enabled. |
| `NODERED_USERNAME` / `NODERED_PASSWORD` | — | Credentials exchanged for a token via `/auth/token`, if you prefer not to mint one by hand. |
| `VOMEHOME_API_URL` | `https://vome.io` | VomeHome portal base URL. |
| `VOMEHOME_TOKEN` | _(disabled)_ | VomeHome personal access token; enables the `vomehome_*` tools. |
| `VOMEHOME_INSTANCE_ID` | _(direct mode)_ | The active/default instance to broker HA calls to. With a token and **no** `HA_TOKEN`, HA tools route through VomeHome (see [Brokered mode](#brokered-mode-the-real-boundary)). What it may do is set by your token's per-instance scopes in the portal (server-enforced). |
| `VOMEHOME_INSTANCES` | _(none)_ | Optional JSON registry to make **multiple** instances known at startup, e.g. `[{"id":"rly-house","label":"home"},{"id":"sbx"}]`. Per-instance `write`/`config` here are optional **local** restrictions (omit to defer to the server). Switch between them with `vomehome_use_instance`. See [Several instances from one token](#several-instances-from-one-token). |
| `VOMEHOME_ALLOW_CREATE` | _(defer to key)_ | Optional **local** guard for creating an instance. The real authority is the account-wide create scope on your API key; set `false` to block creation locally regardless. Instances you create are granted full HA access on that key and become the active target for the session. |
| `HA_TIMEOUT_MS` | `15000` | HTTP/WebSocket request timeout. |
| `MAX_RESULTS` | `500` | Max items a list tool returns before truncating. |
| `LOG_LEVEL` | `info` | `error` \| `warn` \| `info` \| `debug` (logs go to stderr). |

### Getting a token

In Home Assistant: click your user (bottom-left) → **Security** tab → **Long-lived
access tokens** → **Create token**.

---

## Editor setup

This is a standard stdio MCP server, so the same binary works everywhere.

### Cursor

Use the [one‑click button](#one-click-cursor) above, or create `.cursor/mcp.json`
in your project (or `~/.cursor/mcp.json` for all projects). See
[`examples/cursor.mcp.json`](./examples/cursor.mcp.json):

```json
{
	"mcpServers": {
		"home-assistant": {
			"command": "npx",
			"args": ["-y", "@vortitron/home-assistant-mcp"],
			"env": {
				"HA_URL": "http://homeassistant.local:8123",
				"HA_TOKEN": "paste-your-long-lived-token",
				"HA_ALLOW_WRITE": "false"
			}
		}
	}
}
```

### VS Code

Create `.vscode/mcp.json` (see [`examples/vscode.mcp.json`](./examples/vscode.mcp.json)).
VS Code can prompt for the token so it is not stored in the file:

```json
{
	"inputs": [
		{ "id": "ha_token", "type": "promptString", "description": "Home Assistant token", "password": true }
	],
	"servers": {
		"home-assistant": {
			"type": "stdio",
			"command": "npx",
			"args": ["-y", "@vortitron/home-assistant-mcp"],
			"env": {
				"HA_URL": "http://homeassistant.local:8123",
				"HA_TOKEN": "${input:ha_token}"
			}
		}
	}
}
```

### Claude Desktop

Add the same block under `mcpServers` in `claude_desktop_config.json`.

### Claude Code: the side panes

Claude Code takes the same block in `.mcp.json`, or one server at a time with
`claude mcp add-json <name> '<entry>'`. Through Vome it is two commands, with a
key from the Vome app's **Agent** tab:

```
/plugin install vome-connect --marketplace Vortitron/home-assistant-mcp
/plugin install vome-panes --marketplace Vortitron/home-assistant-mcp
```

The first connects your home (it asks for the key), the second installs all
four panes. Or pick them one at a time:

![The automation pane: the automation as a WHEN/THEN map, each step marked by whether its latest run reached it.](docs/images/vome-automation.png)

The [**vome-automation**](claude-plugin/vome-automation/README.md) pane shows
the automation Claude is working on, what a save changed and which steps the
latest run took:

```
/plugin install vome-automation --marketplace Vortitron/home-assistant-mcp
```

That needs Claude Code 2.1.275 or newer; its README has the two-command form
for older versions, how to turn on updates, and the read-only tools to allow in
auto mode.

<img src="docs/images/vome-health.png" alt="The health pane: 72 out of 100, the findings to fix with a Fix button each, and what is fine." width="49%"> <img src="docs/images/vome-dash.png" alt="The dashboard pane: lights, sockets, a camera in half blocks, occupancy, temperatures and their graphs, in two columns." width="49%">

For the home's health, [**vome-health**](claude-plugin/vome-health/README.md)
shows Vome's score and what its check found, marked as Claude fixes each, and
re-scored with a roll and fireworks:

```
/plugin install vome-health --marketplace Vortitron/home-assistant-mcp
```

For a dashboard that works, [**vome-dash**](claude-plugin/vome-dash/README.md)
puts one of yours in a pane: live states, controls that switch and dim,
cameras in half blocks, and the cards Claude changes lit up:

```
/plugin install vome-dash --marketplace Vortitron/home-assistant-mcp
```

For ESPHome, [**vome-esphome**](claude-plugin/vome-esphome/README.md) adds a
pane with a map of the device Claude is working on, drawn from its YAML, and
the build it runs as it happens:

```
/plugin install vome-esphome --marketplace Vortitron/home-assistant-mcp
```

And just for fun, [**dont-panic**](https://github.com/Vortitron/dont-panic)
adds the Guide: a pane that animates whatever the agent is doing and files a
live, irreverent Guide entry on it. Its README has the price levels; `/guide
canned` costs nothing:

```
/plugin install dont-panic --marketplace Vortitron/home-assistant-mcp
```

To connect Claude Code to a home through Vome without any of the config above,
install [**vome-connect**](claude-plugin/vome-connect/README.md) from the same
marketplace; it asks for one key, which the Vome app's Agent tab in Home
Assistant gives you without signing up:

```
/plugin install vome-connect --marketplace Vortitron/home-assistant-mcp
```

### Multiple Home Assistants

Each entry under `mcpServers` is its own server process with its own
environment, so to control several Home Assistants — each with a different
token — add one entry per instance and give each a distinct name. The name
prefixes the tool names in your editor (e.g. `ha-home: ha_list_entities`), so
the agent always knows which house it is talking to. See
[`examples/cursor.multi.mcp.json`](./examples/cursor.multi.mcp.json):

```json
{
	"mcpServers": {
		"ha-home": {
			"command": "npx",
			"args": ["-y", "@vortitron/home-assistant-mcp"],
			"env": {
				"VOMEHOME_TOKEN": "vh_token-for-home",
				"VOMEHOME_INSTANCE_ID": "rly-aaaaaaaaaaaa"
			}
		},
		"ha-cottage": {
			"command": "npx",
			"args": ["-y", "@vortitron/home-assistant-mcp"],
			"env": {
				"VOMEHOME_TOKEN": "vh_token-for-cottage",
				"VOMEHOME_INSTANCE_ID": "rly-bbbbbbbbbbbb"
			}
		}
	}
}
```

Brokered and direct entries mix freely (e.g. a brokered home plus a direct
`HA_URL`/`HA_TOKEN` lab instance), and each entry can carry its own safety
flags — a read-only token for the family home, writes enabled for the test
bench.

### Several instances from one token

**Name the home on any call.** Every tool except the `vomehome_*` ones accepts
an optional `instance_id`. When given, the call is refused if this session is
targeting a different home, instead of answering from it. Writes to files and
logins already require it. Reads need it too: a session that reconnects can
resume on another window's choice, and "entity not found" or an empty history
from the wrong house look like real answers.

The multi-process layout above is one process per token. When several instances
live on the **same** VomeHome account (same token), you can instead drive them
all from **one** server and switch between them at runtime. Permissions live on
the key — you grant `ha:write` / `ha:config` per instance in the portal and the
server enforces it — so the config below is just about which instances are known
at startup (plus any optional local belt-and-braces restrictions).

```json
{
	"mcpServers": {
		"home-assistant": {
			"command": "npx",
			"args": ["-y", "@vortitron/home-assistant-mcp"],
			"env": {
				"VOMEHOME_TOKEN": "vh_your-account-token",
				"VOMEHOME_INSTANCE_ID": "rly-house",
				"VOMEHOME_INSTANCES": "[{\"id\":\"rly-house\",\"write\":false,\"label\":\"home (locked read-only here)\"},{\"id\":\"sbx-plc\",\"label\":\"PLC sandbox\"}]"
			}
		}
	}
}
```

- **`VOMEHOME_INSTANCE_ID`** is the *active/default* instance the `ha_*` tools
  target at startup (folded into the registry automatically as `"default"`).
  What it may do is set by your token's per-instance scopes in the portal.
- **`VOMEHOME_INSTANCES`** declares which instances are known at startup. Listing
  them is optional — the token already reaches them — but it lets you pin the
  active target and add local restrictions. A per-instance `write` / `config`
  here is an **optional local-only** restriction: omit it to defer to the server,
  or set `false` to keep an instance read-only on this machine regardless of what
  the key allows (the example locks the house locally).
- **`vomehome_use_instance`** switches the active instance for subsequent `ha_*`
  calls; **`vomehome_list_instances`** shows which one is active and each
  instance's effective access.
- **Creating instances** (`vomehome_create_instance`) needs the create scope on
  your key — **you own what you create**. The portal grants the creating key
  full Home Assistant access on the new instance (`ha:read`, `ha:write`,
  `ha:config`, `ha:files`) so `ha_*` tools work without a trip back to the
  tokens page. Other keys, and other homes, stay as you ticked them. The
  instance also becomes the active target for the session. Add its id to
  `VOMEHOME_INSTANCES` to keep it known across restarts.

The **API key is the single source of truth** and the server has the final say
(it returns `403` if the key lacks a scope). The client flags above only ever
restrict further on this machine; they never widen what the token can do.

**On Vome's hosted endpoint** (`https://vome.io/mcp`, nothing installed), the
same idea is one URL. A session starts on the instance that client last switched
to, and that choice is remembered across server restarts. To have a project
always start on a particular home, pin it in the URL:

```json
{ "mcpServers": { "vome": { "type": "http", "url": "https://vome.io/mcp?instance=rly-house",
	"headers": { "Authorization": "Bearer vh_your-account-token" } } } }
```

The pin is where sessions start, not a lock: `vomehome_use_instance` still
switches. It only counts while your token can reach that instance.

### Verify

```bash
npx -y @vortitron/home-assistant-mcp doctor
```

`doctor` checks REST, the WebSocket registry and (if configured) the ESPHome
dashboard, and prints a health summary. It never starts the MCP server, so it is
safe to run any time.

---

## Safety

Designed to be safe to point at a real home:

1. **Read-only by default (direct mode).** With a raw `HA_TOKEN` the MCP is the
   only guard, so every state-changing tool refuses until `HA_ALLOW_WRITE=true`.
   In **brokered mode** permissions instead live on your VomeHome API key and are
   enforced server-side per instance (see [Brokered mode](#brokered-mode-the-real-boundary)).
2. **Domain deny-list.** Even with writes on, sensitive domains (locks, alarms,
   covers, valves, cameras) are blocked. In direct mode remove them from
   `HA_DENY_DOMAINS`; in brokered mode tick them for the key under
   *Sensitive devices* on the VomeHome API tokens page.
3. **Optional allow-list.** Set `HA_ALLOW_DOMAINS` to permit *only* specific
   domains.
4. **Cross-domain guard.** `ha_call_service` checks the domain of every target
   entity — including entity ids nested anywhere inside `data` — so a generic
   service (e.g. `homeassistant.turn_on`) cannot be used to reach a denied
   domain. Generic services targeting an **area/device/label** are refused while
   a deny/allow-list is active, because those selectors resolve server-side and
   cannot be checked here; target entity ids or use the domain-specific service
   (e.g. `light.turn_on`) instead.
5. **Separate config-write scope.** Editing automation YAML needs its own
   `ha:config` scope (brokered) or `HA_ALLOW_CONFIG_WRITE=true` (direct).
6. **VomeHome guards.** Rebooting or creating an instance is gated by the matching
   scope on your API key (server-enforced); the optional `VOMEHOME_ALLOW_CREATE`
   client flag can add a local block. The VomeHome token is scoped server-side to
   your own account.

Tools are also annotated with MCP hints (`readOnlyHint`, `destructiveHint`) so
clients can warn before destructive calls.

### What the write‑guard protects (and what it doesn't)

The guard constrains what **these tools** will do, and it's a strong guardrail
when the MCP server is the agent's *only* route to Home Assistant. It is **not** a
cryptographic boundary: a Home Assistant long‑lived token grants full access, so
an agent that *also* holds that token can call the HA API directly and bypass the
guard. So keep the token in your editor's MCP config (ideally `~/.cursor/mcp.json`,
outside any repo the agent can read) — not in files the agent browses.

For a genuine boundary, point the agent at **VomeHome** instead: it holds only a
revocable `VOMEHOME_TOKEN` while the powerful HA credential stays server‑side,
where access is policed and audited — so the agent *can't* go around the policy.
See [Brokered mode](#brokered-mode-the-real-boundary).

---

## Brokered mode (the real boundary)

Direct mode is convenient, but the write‑guard only helps if the agent doesn't
*also* hold the HA token. **Brokered mode closes that gap**: the agent is given a
revocable, scoped [VomeHome](https://vome.io) token and an instance id — and
**no Home Assistant token at all**. Every HA read/write is proxied through the
VomeHome portal, which:

- keeps the HA credential server‑side (the agent never sees it);
- enforces **read / write / config per token, per instance** — a token without
  `ha:write` for an instance genuinely cannot change it, no matter how it's used;
- blocks sensitive domains (locks, alarms, …) server‑side, including via generic
  services (`homeassistant.turn_on` can't reach a lock);
- **audits every call** (allowed or denied) against the token that made it.

Because the policy lives on the server, the agent cannot bypass it — that's the
difference between a guardrail and a boundary.

```json
{
	"mcpServers": {
		"home-assistant": {
			"command": "npx",
			"args": ["-y", "@vortitron/home-assistant-mcp"],
			"env": {
				"VOMEHOME_TOKEN": "vh_paste-your-token",
				"VOMEHOME_INSTANCE_ID": "your-instance-id"
			}
		}
	}
}
```

Mint the token at **Account → API tokens** in the portal. There you grant, **per
instance**, whether it may control Home Assistant (`ha:write`) and/or edit
automation config (`ha:config`) — and you can edit those grants after issuing the
key. The key is the single source of truth; the MCP just carries it. Get the
instance id from the dashboard or the `vomehome_list_instances` tool. (The portal's
token page generates this token-only snippet for you.)

> **Token scopes for the `vomehome_*` tools.** The instance-management tools
> (`vomehome_list_instances`, `_get_instance`, `_use_instance`, `_get_login_url`)
> need the **`instances:read`** scope, and `vomehome_create_instance` needs
> **`instances:write`** (which implies read). A token minted with only the HA
> scopes (`ha:read` / `ha:write` / `ha:config`) can broker Home Assistant calls
> but will get `403 … missing required scope(s): instances:read` from the
> instance tools. If you want the agent to spin up sandboxes, mint the token with
> `instances:write`. Creating an instance grants that key full `ha:*` access
> (`ha:read`, `ha:write`, `ha:config`, `ha:files`) on the **new** instance
> automatically — existing homes keep the grants you ticked. No local
> `VOMEHOME_ALLOW_CREATE` env flag is required in brokered mode (set `false`
> only if you want a local block).
> A default (read-only) token already includes `instances:read` — the 403 only
> appears when a token was scoped to HA access *without* the instances scopes.

Brokered mode proxies the everyday loop — list/get entities, list services, call
services, read config, render templates — **plus automation editing**:
`ha_get_automation`, `ha_set_automation`, `ha_delete_automation` and
`ha_check_config`. **Lovelace dashboards** are brokered too:
`ha_list_dashboards`, `ha_get_dashboard`, `ha_save_dashboard`,
`ha_create_dashboard`, `ha_delete_dashboard` (writes need `ha:config`).
Reading an automation needs `ha:read`; writing one needs the
separate **`ha:config`** scope on the token *for that instance*, enforced
server-side. The client write guards (`HA_ALLOW_WRITE` / `HA_ALLOW_CONFIG_WRITE`)
default permissive in brokered mode and are optional local restrictions on top.
Registry tools (areas/devices), logs and history still need direct mode for now.

**ESPHome over the relay.** When you broker to a **relay-connected** Home
Assistant (your own HA linked via the Vome component's outbound tunnel), ESPHome
comes with it — listing devices, reading and writing YAML, and the streaming
commands (`esphome_validate` / `_compile` / `_upload` / `_logs` / `_clean`), which
ride the relay as polled jobs. Reads need `ha:read`; writing YAML, building and
flashing need the instance's `ha:config` scope. This is the only route: see
[ESPHome](#esphome-brokered-to-a-relay-connected-ha).

**Bring your own Home Assistant.** The instance you broker to does not have to be
a VomeHome VM. In the VomeHome portal, **Account → Connect HA** lets you attach a
Home Assistant you host yourself (public URL / external IP, or Nabu Casa Remote
UI) with a long‑lived access token. It then appears in `vomehome_list_instances`
with an `ext-…` id — set `VOMEHOME_INSTANCE_ID` to that, and the same scoped,
deny‑listed, audited boundary applies. Your HA token stays on the VomeHome server;
the agent only ever gets the revocable VomeHome token.

**Discovery for agents.** VomeHome publishes a machine-readable index of all of
this — how to sign up, mint tokens, boot a trial VM, link a home HA, and the
`/api/v1` surface — as a [Gopher-over-HTTPS](https://seneschal.space/gopher/)
menu at [`https://vome.io/.well-known/agent.gopher`](https://vome.io/.well-known/agent.gopher)
and in [llms.txt](https://llmstxt.org/) form at
[`https://vome.io/llms.txt`](https://vome.io/llms.txt). If you are an agent
reading this: start there.

---

## Example agent workflows

- *"What lights are on in the living room?"* → `ha_list_entities` (domain `light`,
  area `living room`).
- *"Make this template return true only after sunset"* → iterate with
  `ha_render_template`.
- *"Turn the porch light to 30%"* → `ha_call_service` (`light.turn_on`,
  `brightness_pct: 30`). Requires writes enabled.
- *"Fix my morning automation"* → `ha_get_automation` → edit → `ha_set_automation`
  → `ha_check_config` → `ha_trigger_automation`.
- *"Add a sensor to this ESPHome node and flash it"* → `esphome_get_config` →
  `esphome_edit_config` (or `esphome_save_config` for a new file) → `esphome_validate` → `esphome_upload`.
- *"Tidy up my Node-RED 'Heating' tab"* → `nodered_get_flows` (find the tab id)
  → `nodered_get_flow` → edit the nodes → `nodered_update_flow`.
- *"Spin up a sandbox and open it"* → `vomehome_create_instance` →
  `vomehome_get_instance` (poll status) → `vomehome_get_login_url` (open the link).
- *"Why is my Hue integration throwing errors?"* → `ha_get_system_log`
  (`logger: "hue"`) → read `exception_summary` → `ha_get_system_log` again with
  `include_exception: true` for the full stack.
- *"Why didn't my morning automation run?"* → `ha_get_trace`
  (`item: "automation.morning"`) → read `failed_at`.

---

## Debugging with logs

Four surfaces, roughly in the order to reach for them:

| Question | Tool |
| --- | --- |
| What is broken right now? | `ha_get_system_log` |
| Why didn't this automation do anything? | `ha_get_trace` |
| What did the add-on / host do? | `ha_get_supervisor_log` |
| What happened to this entity, and when? | `ha_get_logbook` / `ha_get_history` |

**Start with `ha_get_system_log`, not `ha_get_error_log`.** It reads Home
Assistant's structured error store, where the same failure logged 500 times is
*one* record with `count: 500`, a `source` file:line and first/last-seen stamps.
Tailing the raw log spends far more tokens to say less. Full tracebacks are left
out by default — you still get `exception_summary`, the final line that names the
actual exception — so ask for `include_exception: true` once you know which entry
matters.

**The reproduce loop.** When you can trigger the problem on demand, don't sift
through history at all — make the log contain only your reproduction:

1. `ha_set_log_level` (`integration: "hue", level: "debug"`) — debug on the one
   integration, not globally.
2. `ha_clear_system_log`.
3. Reproduce it (`ha_call_service`, `ha_trigger_automation`, …).
4. `ha_get_system_log` — everything returned was caused by step 3.

Levels are runtime-only and reset on restart. Both write tools need
`HA_ALLOW_WRITE=true` in direct mode, but *not* `HA_ALLOW_CONFIG_WRITE`, and the
domain deny/allow lists don't apply — they change log plumbing, not entities.

**Traces answer what logs can't.** An automation whose condition returned false
logs nothing at all; the trace records it. `ha_get_trace` defaults to the most
recent run and returns `failed_at` — the first step that errored or evaluated
false — alongside the trigger and the ordered steps. Home Assistant keeps only a
few traces per item (5 by default) and none from before the last restart, so
`ha_list_traces` returning nothing usually means "trigger it and look again".

---

## ESPHome notes

- REST endpoints (`/devices`, `/edit`) are used for listing and reading/writing
  YAML. These work over the VomeHome relay as well as directly.
- `validate`, `compile`, `upload`, `logs` and `clean` run over the dashboard's
  multiplexed `/ws` API. Over the relay they are brokered as **jobs**: the portal
  starts one and this client polls it, which is what lets a multi-minute compile
  survive the ordinary HTTP timeouts in between.
- **The Vome component owns the dashboard protocol.** ESPHome split its dashboard
  into `esphome-device-builder`, which replaced the per-command WebSockets
  (`/validate`, `/logs`, …) and the `/edit` REST endpoint with a single `/ws`
  socket; the remaining legacy endpoints are documented upstream as deprecated.
  The component translates `/ws` into the stable line/exit stream the relay
  carries, so this client, the portal and the relay never learn that ESPHome
  moved. Builds go through the dashboard's job queue, so an agent-triggered
  build also shows up in its own "Firmware tasks" panel.
- Requires the Vome add-on at **0.3.30 or later**. Older components speak a
  protocol the dashboard no longer answers; the error says so and names the
  version rather than blaming ESPHome.
- **The relay is preferred over reaching the dashboard directly**, even when both
  would work. Going direct skips the portal's per-instance scope checks and its
  audit log — a revoked token would still be able to flash a device that happened
  to share a network with the agent. It is also the only route that works on a
  default HAOS install, where the add-on's web port is disabled and its ingress
  admits only the Supervisor and localhost.
- **Discovery** (`src/esphome/discovery.ts`) finds a dashboard for direct mode,
  where there is no relay and so no policy layer to bypass. Call
  `esphome_dashboard_info` to see which mode is active and, when nothing is
  reachable, every address that was tried and how each failed.
- The dashboard authorises WebSocket commands with its own cookie/XSRF when a
  **dashboard password** is set, so these commands work against **password-less**
  dashboards or ones reachable on a trusted network / behind an auth-terminating
  proxy. Token/basic auth here only helps for the latter.
- `esphome_upload` validates before it flashes. A device that takes a bad build is
  offline until someone reaches it with a cable, so the cheap check runs first;
  pass `skip_validate: true` to bypass it.

---

## Node-RED notes

- The HA **Node-RED add-on** exposes the editor on port `1880`
  (`http://homeassistant.local:1880`). Point `NODERED_URL` at it.
- If the add-on has a **credential secret / `adminAuth`** set, supply
  `NODERED_TOKEN` (or `NODERED_USERNAME`/`NODERED_PASSWORD`, which the client
  exchanges for a token). An add-on reachable only on your trusted network, or
  behind HA ingress / an auth-terminating proxy, needs no auth here.
- `nodered_set_flows` rewrites **everything** — prefer `nodered_create_flow` /
  `nodered_update_flow` for day-to-day edits. Pass the `rev` from
  `nodered_get_flows` so a concurrent change in the editor is detected rather
  than silently overwritten.
- Node-RED flows are plain JSON, which makes them a natural target for
  alternative front-ends (PLC-style ladder, Scratch/Blockly). That exploration
  lives in the VomeHome repo (`docs/alt_interfaces_plan.md`).

## Development

```bash
npm run dev          # run from source with tsx (watch)
npm run build        # compile to dist/
npm test             # vitest
npm run lint         # eslint
npm run typecheck    # tsc --noEmit
```

Layout:

```
src/
	index.ts              # entry: MCP stdio server + `doctor`/`tunnel` CLI
	config.ts             # env parsing + validation
	safety.ts             # write-guard policy
	logger.ts             # stderr logger
	ha/                   # Home Assistant REST + WebSocket + brokered clients
	esphome/              # ESPHome dashboard client
	nodered/              # Node-RED admin API client
	vomehome/             # VomeHome portal client
	tools/                # one module per tool group
	cli/doctor.ts         # connectivity check
	cli/tunnel.ts         # raw-TCP LAN tunnel client (RDP, etc.)
tests/                  # vitest unit tests
```

---

## Roadmap

- **VomeHome‑brokered HA access (the real boundary) — shipped (MVP).** HA
  reads/writes can be proxied *through* VomeHome with a revocable `VOMEHOME_TOKEN`
  so the HA credential never reaches the agent and the read‑only / deny‑domain /
  audit policy is enforced **server‑side**. Automation editing and the ESPHome
  REST subset are brokered too (the latter over a relay-connected HA). See
  [Brokered mode](#brokered-mode-the-real-boundary). Next: registry (areas/devices)
  over the broker and a per‑token audit view in the portal.
- **VomeHome test installs.** The `vomehome_*` tools already list, create, reboot
  and open instances. Next: point `HA_URL`/`HA_TOKEN` at a freshly created sandbox
  automatically so an agent can try changes there before touching a real home,
  then promote what works. (Requires the portal API endpoints described in
  [`project_outline.md`](./project_outline.md).)
- **ESPHome over the relay — shipped.** Builds, flashing and device logs are
  brokered as polled jobs, so a remote agent can flash hardware with no inbound
  exposure and with scope checks and audit in front of every command. Next:
  device adoption (the `/import` + wizard flow), so an agent can take a brand-new
  board from unflashed to working entity without a UI step.
- **Node-RED** — flow read/write/deploy shipped. Next: brokering the admin API
  through VomeHome (as HA and the ESPHome REST subset already are) so a
  relay-connected home needs no directly-reachable Node-RED URL, and a flow
  *diff/validate* step before deploy.
- MCP resources for entities/areas (in addition to tools).
- Optional HTTP/SSE transport for remote use.

---

## License

[MIT](./LICENSE) © Vortitron