Home Assistant MCP README

home-assistant-mcp

A Model Context Protocol (MCP) server that lets coding agents — Cursor, VS Code (Copilot), Claude Desktop and anything else that speaks MCP — talk directly to Home Assistant and (optionally) the ESPHome 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.

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).

Part of the Vome 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).

Tools

Home Assistant — read

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.

Lovelace dashboards (direct HA or VomeHome brokered)

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)

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 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).

VomeHome (require VOMEHOME_TOKEN)

VomeHome 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.

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

Supervisor / Vome add-on (HAOS / Supervised)

HACS (Home Assistant Community Store)

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

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)

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:

{
	"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

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.)

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.

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 above, or create .cursor/mcp.json in your project (or ~/.cursor/mcp.json for all projects). See examples/cursor.mcp.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). VS Code can prompt for the token so it is not stored in the file:

{
	"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 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.

For the home's health, vome-health 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 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 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 is house.wad 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 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 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:

{
	"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).

{
	"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:

{ "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

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).
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)

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 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.

{
	"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.

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 menu at https://vome.io/.well-known/agent.gopher and in llms.txt form at 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:

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

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. 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.)
• 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 © Vortitron