home-assistant-mcp
# 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)
[](https://hol.org/guard/extensions/mcp.vome-home-assistant)

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) for an automation made in the editor. One written in a YAML package or included file is named as such, with what to search for to find its file. |
| `ha_check_config` | Validate the configuration (Check configuration). |
| `ha_wait_until_running` | Wait (up to 120 s) for Home Assistant to finish restarting, checking its core state every 5 s. While it restarts, the other tools say "Home Assistant is restarting (core state: …)" or "not answering — it may be restarting" instead of a raw 502, nginx 404 or WebSocket error. When the home is a CHAP pair's main and its standby is running the home (failover), they say that instead, name the standby and how to reach it (`instance_id` on the call, or `vomehome_use_instance`); the CHAP status is asked once per half minute at most, and only for restart-shaped failures. |
| `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_list_media_files` / `ha_read_media_file` | Read-only look into `/media`: a saved camera snapshot comes back as an image (needs `ha:files`, and Vome add-on 0.3.66 / integration 0.9.51 on the home). |
| `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). Where no component is connected (a hosted home without the Vome add-on, a direct connection) it reads the states every ~3 s for the same wait and answers in the same shape with `mode: "polling"`; a 401/403 is never papered over. |
| `ha_get_logbook` | Human-readable logbook entries, filtered by `entity_id`, `contains` (message, name or entity_id), `name` (e.g. `Vome`) and `domain`. At most `limit` (default 500) come back, the newest, with `count_before_limit`, `truncated` and `older_entries_end_time` to read further back. A window longer than a day is read a day at a time, newest first, stopping as soon as `limit` entries match (at most 31 days per call), so Home Assistant is never asked for more than 24 hours at once. |
| `ha_get_energy_prefs` | The Energy dashboard's setup (grid, solar, battery, gas, water, tracked devices) with the dashboard's own validation. |
| `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, …). A service that can return a response (`shell_command`'s stdout/stderr/returncode, `script`, `weather.get_forecasts` …) is asked for it, and it comes back as `service_response`. |
| `ha_speech_to_text` | Run a WAV (16-bit PCM, at most 30 s) through one of the home's speech-to-text engines (`stt.*`) and get back the words it heard, to test an assistant's hearing without speaking to a device. `audio_path` reads a local file (npx servers only); `audio_base64` sends the bytes (the hosted MCP). Language defaults to the home's own. Engines want 16 kHz mono (`ffmpeg -i in.wav -ar 16000 -ac 1 -sample_fmt s16 out.wav`). A write because some engines (Vome Hearing, cloud ones) charge per request: needs `HA_ALLOW_WRITE` / `ha:write`; not for external homes through VomeHome. |
| `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_upload_file` | Copy a file already on disk (a web page, an image, a package) into the config directory: read from the MCP server's own filesystem, sent as text or base64 as it needs, at most 2 MiB, written and checked like `ha_write_config_file`. Local (npx) servers only — the hosted MCP can't see your files and answers with the equivalent `curl` upload (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, folders first: `glob` filters by name (`*.yaml`) or path (`**/*.html`), `offset`/`limit` page (default 200), and the reply gives `total_entries`, `total_bytes` (this folder's own files, not subfolders) and `truncated` when the home stopped at its 500-entry cap (needs `ha:files`). |
| `ha_move_config_file` | Move or rename one file under the config directory, creating folders on the way; never overwrites unless asked. Names its target home like a write (needs `ha:files`, and Vome add-on 0.3.66 / integration 0.9.51). |
| `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_update_device` | Rename a device, move it to an area, disable it or set its labels (needs `HA_ALLOW_CONFIG_WRITE`). |
| `ha_expose_entities` | List or change what Assist, Alexa and Google Assistant can see and control; listing needs only read (changing needs `HA_ALLOW_CONFIG_WRITE`). |
| `ha_set_energy_prefs` | Change the Energy dashboard's setup; each list passed replaces that list whole, then it is validated (needs `HA_ALLOW_CONFIG_WRITE`). |
| `ha_get_statistics` | Read long-term statistics (what the Energy dashboard draws) per 5 minutes to month; `largest_changes` lists the biggest buckets, like the Outliers button. |
| `ha_adjust_statistic` | Correct one 5-minute bucket of a statistic, by new value or by adjustment, as Developer Tools → Statistics does (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_update_dashboard` | Change a dashboard's title, icon, sidebar or admin setting, keeping its cards (needs `HA_ALLOW_CONFIG_WRITE`). |
| `ha_delete_dashboard` | Delete a dashboard by id, cards and all (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 as compact rows (name, friendly name, configuration, address/ip, versions, state); `filter` (substring of name, friendly name, filename or address/ip), `limit` (default 50, max 500), `full: true` for the dashboard's own rows. Says `total`, `matched` and `truncated`; 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 or a large rewrite (write-gated). Inline as `yaml`, or `yaml_path`, a file on the MCP's own machine (npx / stdio; UTF-8, at most 2 MiB) so a long config is not pasted into the call. The hosted MCP cannot read your disk and answers with the REST upload into `esphome/` instead. |
| `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). For a large rewrite, use `esphome_save_config` with `yaml_path` rather than huge edits. |
| `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 kind (hosted, relay, external), status, tier, URL, live health, the **active** instance and per-instance client write/config access. One the portal cannot reach right now (a disconnected relay, a retired home) is marked `offline: true` with a note. |
| `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_list_backups` | Backups in the home's Vome backup location (needs `ha:files`). |
| `vomehome_backup_download_link` | A link to download one backup's `.tar`, good for about 15 minutes (needs `ha:files`). |
| `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`), reconfigure an existing entry (`entry_id`) 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, …). A `…/logs` read is served from the log route, since `supervisor/api` cannot carry plain text, and add-on start/stop/restart wait 50 s instead of Home Assistant's 10. |
| `ha_addon_install_vome` | Add `https://github.com/Vortitron/VomeSync` to the store, install **Vome**, and start it. |
### Community store: the Marketplace (2026.11+) or HACS
The `ha_hacs_*` names predate Home Assistant 2026.11, which built HACS into
Core as the **Marketplace**. Each tool asks `marketplace/info` first and uses
the Marketplace's own commands when it is there, falling back to HACS's
`hacs/*` on older Home Assistants. The names stayed so existing permission
rules and prompts keep working.
| Tool | Description |
| --- | --- |
| `ha_hacs_info` | Which store this home has (`marketplace` or `hacs`) and its status; for the Marketplace, whether GitHub is connected and whether an admin has accepted its warning. |
| `ha_hacs_list_repositories` | List repositories the store knows about. Installed ones only by default, trimmed to id, name, category, installed/available version and `pending_update`; `installed_only: false` or `search` looks through the catalogue, `categories` and `limit` (default 100) narrow it, `full: true` returns raw rows. |
| `ha_hacs_add_repository` | Add a custom repository by `owner/repo` and category. The Marketplace only adds one once GitHub is connected in Settings → Marketplace. Confirms by re-listing, since HACS acks even a failed add. Needs `ha:config` (`HA_ALLOW_CONFIG_WRITE` in direct mode). |
| `ha_hacs_download_repository` | Install (or update) a tracked repository — the step that actually writes its files. Needs `ha:config` (`HA_ALLOW_CONFIG_WRITE` in direct mode). |
| `ha_hacs_remove_repository` | Uninstall a repository's files and stop tracking it. Needs `ha:config` (`HA_ALLOW_CONFIG_WRITE` in direct mode). |
There is no REST API or service call for managing repositories — these go
over the store's WebSocket commands, the same way as the Supervisor tools
above. Adding a repository only registers it; call
`ha_hacs_download_repository` afterwards to install it. With HACS, restart
Home Assistant before setting up a new integration; the Marketplace loads a
first install straight away and raises a repair when an update needs a
restart. Nothing installs through the Marketplace until an admin has accepted
its warning in Settings → Marketplace, and there is deliberately no tool for
that.
### People
| Tool | Description |
| --- | --- |
| `ha_list_people` | List the people (Settings → People): linked user, device trackers, and whether each can be edited here (not if defined in configuration.yaml). |
| `ha_set_person` | Create or change a person: name, linked user, picture and device trackers. `add_device_trackers` / `remove_device_trackers` swap one tracker at a time, such as an old phone for a new one. Needs `HA_ALLOW_CONFIG_WRITE`. |
| `ha_delete_person` | Delete a person; its user and trackers stay. Needs `HA_ALLOW_CONFIG_WRITE`. |
### 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 ≥ 20**. 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)
[](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 [**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 for fun, [**vome-doom**](claude-plugin/vome-doom/README.md) is
[house.wad](https://github.com/Vortitron/housewad) in a pane: your home as a
Doom level, where shooting a lamp turns it off for real:
```
/plugin install vome-doom --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`, which **routes that one call** to the named home:
the session's active instance does not move, and on the hosted server nothing
is remembered for the key. Write/config permission is the named home's own,
exactly as if it were active, and the reply's `[vome-instance]` stamp names the
home that answered, adding `(this call only; session still on <active>)` when
that is not the session's. Only an instance the session knows (declared, listed
for the token, created or switched to) is accepted; any other id is refused
with the list of valid ones, so a typo never answers from the active home.
Writes to files and logins (`ha_write_config_file`, `ha_upload_file`,
`ha_edit_config_file`, `ha_delete_config_file`, `ha_move_config_file`,
`ha_provision_service_login`) need `instance_id` **when this key reaches more
than one home**, so a write always lands on the home named: left out, they are
refused with the homes to choose from ("This key reaches 3 homes (a, b, c):
name the one this write is for with instance_id"). When only one home is in
reach they default to it, and the stamp adds `(instance_id omitted: the only
home this session reaches)`. "In reach" is the instances the portal lists for
the token on the hosted server, and `VOMEHOME_INSTANCE_ID` /
`VOMEHOME_INSTANCES` on stdio, plus any the session creates or switches to; a
direct connection has one. Use it to read a CHAP standby while failover is active, or to
compare two homes, without switching. A direct connection (`HA_URL`) has one
Home Assistant and refuses an optional `instance_id` naming anything else.
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.
On a session's first tool call the MCP asks the portal whether the starting
instance is online. If it is offline and was somebody's choice (a pin, a
remembered switch, or `VOMEHOME_INSTANCE_ID`), the session stays on it and the
reply carries a `[vome-notice] WARNING` naming the instances that are online;
the warning comes back on error replies until you switch. If nobody chose it
(it was just first on the account), the session starts on the first online
instance instead and the reply says so. That fallback is not remembered as a
choice.
### 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_update_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
TDQS
Scored across 111 tools
Most tools target distinct actions and have strong descriptions, but the 111-tool surface contains several overlapping clusters: entity lookup vs. state vs. registry, multiple log readers, config-file editing vs. helper/automation/dashboard editing, HACS vs. config entries, and ESPHome vs. HA config editing. The descriptions mitigate most confusion, but an agent can still misselect among related tools.
Names are mostly consistent snake_case with domain prefixes (ha_, esphome_, nodered_, vomehome_, vome_) and follow a verb_noun pattern. Minor deviations exist: two Vome prefixes (vomehome_ vs. vome_), and a few long noun-first names such as vomehome_chap_standby_candidates.
111 tools is extreme and well beyond any reasonable single-server surface. Even accounting for Home Assistant's breadth, this bundles multiple sub-products (HA core, ESPHome, Node-RED, VomeHome, CHAP, HACS) into one enormous tool list, imposing heavy context and selection costs.
Coverage is very broad: entities, automations, scripts, dashboards, helpers, users, config files, logs, HACS, ESPHome, Node-RED, and VomeHome/CHAP lifecycle operations are all represented. Some gaps remain, such as native area/floor/label CRUD or first-class scene management, but most can be worked around via service calls or config-file editing.