home-assistant-mcp
Provides tools for working with the ESPHome dashboard: listing devices and pending config renames/migrations, reading, saving and doing in-place find-and-replace edits of device YAML configurations, validating and compiling firmware, flashing a device over the air, reading live device logs (boot, wifi, sensors, crashes), and cleaning stale build caches. Reached through the VomeHome relay rather than a directly exposed dashboard.
Provides direct tools for talking to a Home Assistant instance: discovering entities, areas, devices and services, reading live states/attributes, history and the logbook, rendering Jinja templates against live state, checking configuration, inspecting deduplicated structured errors and traces, calling services, creating/updating/deleting/triggering automations and scripts, managing helpers and entity registry entries, editing config files, and reading/writing Lovelace dashboards. Write operations are off by default and gated behind an explicit safety policy/scopes.
Allows an agent to read and write the flow JSON of a Node-RED instance (typically the Home Assistant add-on), so flows can be edited by the agent instead of by hand.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@home-assistant-mcp set the living room lights to 40% and turn on the coffee maker"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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).
Related MCP server: Home Assistant MCP Server
Tools
Home Assistant — read
Tool | Description |
| Core config: version, location, time zone, loaded components. |
| List entities (filter by domain, free-text search, area). |
| Full state + attributes for one or more entities. |
| 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); |
| Available services (and their fields for a given domain). |
| Areas (rooms/zones). |
| Device registry (filter by area / search). |
| Registry metadata: platform, area, device, disabled/hidden. |
| Render a Jinja2 template against live state. |
| List stored helpers (input_boolean, input_number, counter, timer, …). |
| Automations with entity_id, unique id, state, last-triggered. |
| 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. |
| Validate the configuration (Check configuration). |
| 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 ( |
| Deduplicated, structured errors — level, logger, source, count, first/last seen. Start here. |
| Tail of the raw Home Assistant error log. |
| Add-on / Core / Supervisor / host logs (HAOS or Supervised). |
| Read-only look into |
| A camera's current still, as an image the agent can see. Via VomeHome the key needs Cameras ticked. |
| A camera still decoded and shrunk to a small grid of RGB pixels, for clients that draw pictures in text. |
| Everything a dashboard view shows in one call: states, rendered templates, history in few points, camera frames. For dashboard clients. |
| 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 |
| Human-readable logbook entries, filtered by |
| The Energy dashboard's setup (grid, solar, battery, gas, water, tracked devices) with the dashboard's own validation. |
| Recent automation/script runs and how each one stopped. |
| Step-by-step detail for one run, with |
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-instanceha:write/ha:configscopes and the server enforces them, so the client flags are optional local-only restrictions.
Tool | Description |
| Call any service (turn_on, set_temperature, …). A service that can return a response ( |
| Run a WAV (16-bit PCM, at most 30 s) through one of the home's speech-to-text engines ( |
| Empty the structured error store (only needs |
| Change logging for one integration at runtime (only needs |
| Create or update an automation (also needs |
| Create or update a helper — no |
| Read a file under the config directory — text by default, or |
| Replace a file under the config directory — text by default, or |
| 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 |
| Delete one file under the config directory. Never a directory, and never |
| 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 |
| List a directory under the config directory, folders first: |
| 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 |
| Delete a stored helper. Refuses when the id looks shared with a |
| Delete an automation (also needs |
| Scripts by id, the same way as automations: put a step several automations share in one script. Writes need |
| Rename, re-id, move, re-icon, disable or hide an entity in the registry (needs |
| Rename a device, move it to an area, disable it or set its labels (needs |
| List or change what Assist, Alexa and Google Assistant can see and control; listing needs only read (changing needs |
| Change the Energy dashboard's setup; each list passed replaces that list whole, then it is validated (needs |
| Read long-term statistics (what the Energy dashboard draws) per 5 minutes to month; |
| Correct one 5-minute bucket of a statistic, by new value or by adjustment, as Developer Tools → Statistics does (needs |
| Remove an orphaned registry entry (needs |
| The Matter device page's Re-interview, for a device whose endpoints changed after a firmware update (needs |
| Manually run an automation now. |
| Reload automations without restarting. |
Lovelace dashboards (direct HA or VomeHome brokered)
Tool | What it does |
| List dashboards ( |
| Read one dashboard's full config (views, cards, …). |
| Save/replace a dashboard config (needs |
| Register a new storage-mode dashboard (needs |
| Change a dashboard's title, icon, sidebar or admin setting, keeping its cards (needs |
| Delete a dashboard by id, cards and all (needs |
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 |
| How ESPHome is reached, and whether flashing/logs are available right now. |
| List dashboard configurations/devices as compact rows (name, friendly name, configuration, address/ip, versions, state); |
| ESPHome spellings a config still uses that have been renamed. |
| Read a configuration's YAML. |
| Write a configuration's YAML, whole: for a new file or a large rewrite (write-gated). Inline as |
| 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 |
| Vome's health score for the home and every finding, with severity, evidence, a recommendation and the entities involved. |
| Run a fresh health check, to re-score after fixes (write-gated). |
| Validate a configuration. |
| Compile firmware. |
| Compile + flash a device over the air; validates first (write-gated). |
| Read a device's live logs — boot, wifi, sensors, crashes. |
| 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 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 |
| Get the full flow config (all tabs) plus the current revision. |
| Get one flow (tab) and its nodes by id. |
| List installed node modules/types (the palette). |
| Add a new tab without disturbing existing flows (write-gated). |
| Replace one tab by id, leaving others untouched (write-gated). |
| Delete a tab and its nodes (write-gated). |
| Replace the entire flow config and deploy (write-gated). |
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.
Tool | Description |
| 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 |
| Details + live status for one instance. |
| Switch which instance the |
| Reboot an instance's VM (write-gated). |
| 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). |
| Mint a one-click HA login URL to open in a new tab. |
| Backups in the home's Vome backup location (needs |
| A link to download one backup's |
| Create a non-admin HA user + one-click login URL for sharing (needs |
| List guest links for an instance, revoked ones included. |
| 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 |
| List installed integrations (config entries). Optional domain filter. |
| 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 |
| List integrations Home Assistant has discovered on the network but not yet added. |
| Start ( |
| Read or set an integration's options — including ESPHome's |
| Add the Vome ( |
Supervisor / Vome add-on (HAOS / Supervised)
Tool | Description |
| Call a Supervisor endpoint via |
| Add |
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 |
| Which store this home has ( |
| List repositories the store knows about. Installed ones only by default, trimmed to id, name, category, installed/available version and |
| Add a custom repository by |
| Install (or update) a tracked repository — the step that actually writes its files. Needs |
| Uninstall a repository's files and stop tracking it. Needs |
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 |
| List the people (Settings → People): linked user, device trackers, and whether each can be edited here (not if defined in configuration.yaml). |
| Create or change a person: name, linked user, picture and device trackers. |
| Delete a person; its user and trackers stay. Needs |
Users
Tool | Description |
| List every user: id, name, username, role, active/owner status. |
| Create a user with a role ( |
| Change a user's name, role, active state, or local-only restriction. Needs |
| Permanently delete a user and its login. Needs |
| Give a user with no login yet a username/password. Needs |
| Reset the password for a user that already has a login. Needs |
| Remove a login without deleting the user. Needs |
| 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 |
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)
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 buildLAN TCP tunnels (RDP, etc.)
npx -y @vortitron/home-assistant-mcp tunnel --token <jwt> --local-port 3390Opens 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 |
| — (required) | Base URL, e.g. |
| — (required) | Long-lived access token (Profile → Security). |
| off (direct) / permissive (brokered) | Local write guard. In brokered mode the API key's per-instance scope decides (server-enforced); setting |
|
| 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. |
| (any) | If set, only these domains may be written. |
| off (direct) / permissive (brokered) | Local guard for editing automation config. Same semantics as |
| (disabled) | Node-RED editor/admin base URL, e.g. |
| — | Bearer token if Node-RED |
| — | Credentials exchanged for a token via |
|
| VomeHome portal base URL. |
| (disabled) | VomeHome personal access token; enables the |
| (direct mode) | The active/default instance to broker HA calls to. With a token and no |
| (none) | Optional JSON registry to make multiple instances known at startup, e.g. |
| (defer to key) | Optional local guard for creating an instance. The real authority is the account-wide create scope on your API key; set |
|
| HTTP/WebSocket request timeout. |
|
| Max items a list tool returns before truncating. |
|
|
|
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-mcpThe 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-mcpThat 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-mcpFor 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-mcpFor 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-mcpAnd 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-mcpAnd 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-mcpTo 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-mcpMultiple 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, 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).
{
"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_IDis the active/default instance theha_*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_INSTANCESdeclares 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-instancewrite/confighere is an optional local-only restriction: omit it to defer to the server, or setfalseto keep an instance read-only on this machine regardless of what the key allows (the example locks the house locally).vomehome_use_instanceswitches the active instance for subsequentha_*calls;vomehome_list_instancesshows 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) soha_*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 toVOMEHOME_INSTANCESto 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.
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
npx -y @vortitron/home-assistant-mcp doctordoctor 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:
Read-only by default (direct mode). With a raw
HA_TOKENthe MCP is the only guard, so every state-changing tool refuses untilHA_ALLOW_WRITE=true. In brokered mode permissions instead live on your VomeHome API key and are enforced server-side per instance (see Brokered mode).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.Optional allow-list. Set
HA_ALLOW_DOMAINSto permit only specific domains.Cross-domain guard.
ha_call_servicechecks the domain of every target entity — including entity ids nested anywhere insidedata— 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.Separate config-write scope. Editing automation YAML needs its own
ha:configscope (brokered) orHA_ALLOW_CONFIG_WRITE=true(direct).VomeHome guards. Rebooting or creating an instance is gated by the matching scope on your API key (server-enforced); the optional
VOMEHOME_ALLOW_CREATEclient 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:writefor 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_oncan'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 theinstances:readscope, andvomehome_create_instanceneedsinstances: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 get403 … missing required scope(s): instances:readfrom the instance tools. If you want the agent to spin up sandboxes, mint the token withinstances:write. Creating an instance grants that key fullha:*access (ha:read,ha:write,ha:config,ha:files) on the new instance automatically — existing homes keep the grants you ticked. No localVOMEHOME_ALLOW_CREATEenv flag is required in brokered mode (setfalseonly if you want a local block). A default (read-only) token already includesinstances: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.
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(domainlight, arealiving 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(oresphome_save_configfor 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") → readexception_summary→ha_get_system_logagain withinclude_exception: truefor the full stack."Why didn't my morning automation run?" →
ha_get_trace(item: "automation.morning") → readfailed_at.
Debugging with logs
Four surfaces, roughly in the order to reach for them:
Question | Tool |
What is broken right now? |
|
Why didn't this automation do anything? |
|
What did the add-on / host do? |
|
What happened to this entity, and when? |
|
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:
ha_set_log_level(integration: "hue", level: "debug") — debug on the one integration, not globally.ha_clear_system_log.Reproduce it (
ha_call_service,ha_trigger_automation, …).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,logsandcleanrun over the dashboard's multiplexed/wsAPI. 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/editREST endpoint with a single/wssocket; the remaining legacy endpoints are documented upstream as deprecated. The component translates/wsinto 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. Callesphome_dashboard_infoto 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_uploadvalidates 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; passskip_validate: trueto bypass it.
Node-RED notes
The HA Node-RED add-on exposes the editor on port
1880(http://homeassistant.local:1880). PointNODERED_URLat it.If the add-on has a credential secret /
adminAuthset, supplyNODERED_TOKEN(orNODERED_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_flowsrewrites everything — prefernodered_create_flow/nodered_update_flowfor day-to-day edits. Pass therevfromnodered_get_flowsso 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 --noEmitLayout:
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 testsRoadmap
VomeHome‑brokered HA access (the real boundary) — shipped (MVP). HA reads/writes can be proxied through VomeHome with a revocable
VOMEHOME_TOKENso 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: pointHA_URL/HA_TOKENat 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 inproject_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
Available Tools
111 toolsesphome_activityESPHome build activityARead-only
What the ESPHome build commands (validate, compile, upload, logs) started in this session are doing: each running or recently finished job with its newest output lines. Pass back the returned 'seq' as 'since' to get only lines produced after it. For watching a long build while it runs; the build tools themselves return the full output when they finish.
Inputs: since, instance_id.
esphome_cleanClean ESPHome build filesADestructive
Delete the cached build files for a configuration. Use this when a compile fails for reasons the YAML does not explain — a stale build directory after an ESPHome version change is the usual cause. Then compile again. Runs over the VomeHome relay — no ports to open. If a call reports that ESPHome is unreachable, run esphome_dashboard_info to see why rather than telling the user this is unsupported.
Inputs: configuration (required), instance_id, timeout_seconds.
esphome_compileCompile ESPHome firmwareA
Compile firmware for an ESPHome configuration and return the build output. Can take several minutes. Runs over the VomeHome relay — no ports to open. If a call reports that ESPHome is unreachable, run esphome_dashboard_info to see why rather than telling the user this is unsupported.
Inputs: configuration (required), full_output, instance_id, timeout_seconds.
esphome_dashboard_infoCheck ESPHome capabilityARead-only
Report whether ESPHome is reachable and what is possible right now — listing and editing configs, and the streaming commands (validate/compile/upload/logs/clean). ESPHome is reached through a VomeHome relay-connected Home Assistant running the Vome add-on; when that is in place everything is available. Call this before telling a user that flashing or log-reading is unsupported — it usually is not.
Inputs: instance_id.
esphome_edit_configEdit ESPHome configADestructive
Change part of an ESPHome configuration file in place: each edit replaces one exact piece of text with another, and must match exactly once. Prefer this to esphome_save_config for any change to an existing file: a real device's YAML runs to thousands of lines, and resending all of it to change a few is slow and risks a slip anywhere in it. Nothing is saved unless every edit applies. Requires HA_ALLOW_WRITE=true and HA_ALLOW_CONFIG_WRITE=true. Follow with esphome_validate, then esphome_upload to flash it.
Inputs: edits (required), configuration (required), instance_id.
esphome_get_configGet ESPHome configBRead-only
Read the YAML for an ESPHome configuration file (e.g. 'living-room.yaml').
Inputs: configuration (required), instance_id.
esphome_list_devicesList ESPHome devicesARead-only
List devices/configurations known to the ESPHome dashboard, including their configuration filenames (needed by the other ESPHome tools).
Inputs: instance_id.
esphome_list_migrationsCheck a config for ESPHome renamesARead-only
Report the ESPHome spellings a device's YAML still uses that have since been renamed — the same 'Config migration available' notice the ESPHome dashboard shows in its own UI, which is otherwise invisible from here. Each entry names the old and new spelling and the ESPHome release that changed it.
required: true means the installed ESPHome already rejects the old spelling, so the config will fail to compile until it is fixed; otherwise it still works but is on borrowed time. Apply a rename by editing the YAML with esphome_save_config.
Inputs: configuration (required), instance_id.
esphome_logsRead ESPHome device logsARead-only
Stream the live logs from an ESPHome device and return what was captured. This is the way to see what a device is actually doing — boot messages, wifi/API connection problems, sensor readings, crashes and reboot reasons. Use it after flashing, or whenever a device is behaving oddly. Returns once the timeout elapses, so set timeout_seconds to how long you want to watch. Runs over the VomeHome relay — no ports to open. If a call reports that ESPHome is unreachable, run esphome_dashboard_info to see why rather than telling the user this is unsupported.
Inputs: configuration (required), port, full_output, instance_id, +1 more.
esphome_save_configSave ESPHome configADestructive
Write YAML to an ESPHome configuration file, whole: for a new file. To change part of an existing one, use esphome_edit_config. Requires HA_ALLOW_WRITE=true and HA_ALLOW_CONFIG_WRITE=true. Follow with esphome_validate to confirm it compiles, then esphome_upload to flash it.
Inputs: yaml (required), configuration (required), instance_id.
esphome_uploadFlash ESPHome firmware (OTA)ADestructive
Compile and flash firmware to a device over the air. This is how you update an ESPHome device — no cable, no manual step in the ESPHome UI. 'port' is the device address or 'OTA' (the default). Requires write access. The build runs first and a failed build never reaches the device. Runs over the VomeHome relay — no ports to open. If a call reports that ESPHome is unreachable, run esphome_dashboard_info to see why rather than telling the user this is unsupported.
Inputs: configuration (required), port, full_output, instance_id, +1 more.
esphome_validateValidate ESPHome configARead-only
Validate (compile-check) an ESPHome configuration and return the output. The fast way to confirm a YAML edit is correct before compiling or flashing. Runs over the VomeHome relay — no ports to open. If a call reports that ESPHome is unreachable, run esphome_dashboard_info to see why rather than telling the user this is unsupported.
Inputs: configuration (required), full_output, instance_id, timeout_seconds.
ha_addon_install_vomeInstall the Vome add-onADestructive
Developer helper: add the VomeSync GitHub add-on repository to the Supervisor store (if missing), install the Vome add-on, and start it. Requires HAOS/Supervised. In brokered mode the API key's ha:config scope is authoritative — no HA_ALLOW_WRITE env flag needed. After install, restart Home Assistant once so custom_components/vomesync is loaded, then add the Vome integration.
Inputs: skip_start, instance_id, repository_url.
ha_call_serviceCall a serviceADestructive
Call a Home Assistant service to change state (e.g. domain='light', service='turn_on', data={ brightness_pct: 60 }, target={ entity_id: 'light.kitchen' }). Refused unless writes are enabled, and blocked for denied domains. Returns the entities that changed.
Inputs: domain (required), service (required), data, target, +1 more.
ha_camera_frameA camera still as pixelsARead-only
A camera's current still decoded and shrunk to at most width x height pixels, returned as RGB bytes (base64, 3 a pixel, row by row): for a client that draws pictures in text, such as a dashboard pane in a terminal (two pixels a character cell with half blocks). To look at a camera yourself, use ha_camera_image. Through VomeHome the API key needs Cameras ticked under Sensitive devices.
Inputs: width (required), height (required), entity_id (required), instance_id.
ha_camera_imageLook at a cameraARead-only
Return a camera's current still as an image you can see — to check framing, exposure, or what the camera shows. For a camera entity that shows the latest snapshot file, this is that snapshot. Home Assistant scales it to 'width' pixels wide (default 1024). Through VomeHome the API key needs Cameras ticked under Sensitive devices.
Inputs: entity_id (required), width, instance_id.
ha_change_user_passwordChange a user's passwordADestructive
Reset the password for a user that already has a local login (created via ha_set_user_credentials or Home Assistant's own UI). Only works when the broker is acting as the home's owner account, which is how it always authenticates. Requires ha:config.
Inputs: user_id (required), password (required), instance_id.
ha_check_configCheck configurationARead-only
Validate the current Home Assistant configuration (equivalent to Developer Tools -> Check configuration). Returns 'valid' or the specific errors. Run this after editing YAML and before reloading.
Inputs: instance_id.
ha_clear_system_logClear system logADestructive
Empty Home Assistant's structured error store. The point is the debug loop: clear, reproduce the problem, then ha_get_system_log shows only what your reproduction caused. Does not touch home-assistant.log on disk. Requires HA_ALLOW_WRITE=true in direct mode.
Inputs: instance_id.
ha_config_entry_optionsRead or change an integration's optionsADestructive
Open a config entry's options flow — the per-integration settings panel — and optionally submit answers to it. Call with entry_id alone to see the current form and its fields, then again with user_input to set them.
This is the only way to reach switches that exist nowhere else in the API. The one asked for most: ESPHome's 'allow the device to perform Home Assistant actions' (field allow_service_calls), which a device needs before it can call HA services and which is buried several clicks deep in the UI. Also on that form: subscribe_logs. Get entry_id from ha_list_config_entries (domain=esphome).
Submitting a form sets every field it contains, so read it first and send the values back with only the ones you mean to change altered — omitting a field is not the same as leaving it alone.
Inputs: flow_id, entry_id, user_input, instance_id.
ha_config_flowStart or continue a config flowADestructive
Add or configure an integration via Home Assistant's config flow API. Start: pass handler (domain). Continue: pass flow_id + user_input for the current step. Requires ha:config (brokered) or HA_ALLOW_CONFIG_WRITE (direct).
Inputs: flow_id, handler, user_input, instance_id, +1 more.
ha_create_dashboardCreate Lovelace dashboardA
Register a new storage-mode Lovelace dashboard. After creating, call ha_save_dashboard to set its views/cards. Requires HA_ALLOW_WRITE=true and HA_ALLOW_CONFIG_WRITE=true.
Inputs: title (required), url_path (required), icon, instance_id, +3 more.
ha_create_userCreate a Home Assistant userADestructive
Create a new Home Assistant user with no login yet — call ha_set_user_credentials afterwards to give them a username and password, or they exist but cannot sign in.
A user this creates is a standing account on the home, independent of any API key. Deleting the token that created it does not remove the user. Choose 'role' deliberately: 'admin' grants full control of this Home Assistant, equivalent to the owner. Requires ha:config.
Inputs: name (required), role (required), local_only, instance_id.
ha_delete_automationDelete automationADestructive
Delete an automation by its unique id. Requires HA_ALLOW_WRITE=true and HA_ALLOW_CONFIG_WRITE=true.
Inputs: automation_id (required), instance_id.
ha_delete_config_entryDelete a config entry (integration)ADestructive
Permanently delete one config entry (integration instance) by id. This is the fix for orphaned or duplicate entries — the kind left behind when a device's original config entry never got cleaned up, so a re-added device's entities pick up a '_2' (or higher) suffix because the old entry is still holding the original entity_id. Get entry_id from ha_list_config_entries; match on name/domain/state to find the stale one before deleting.
There was previously no way to do this outside the Settings → Devices & services UI. Requires ha:config. The response's require_restart says whether Home Assistant needs a restart to fully drop the entry.
Inputs: entry_id (required), instance_id.
ha_delete_config_fileDelete a file in Home Assistant's config directoryADestructive
Delete one file under the config directory — a throwaway test file, a superseded package, something you wrote and no longer need. It deletes a single file only, never a directory. The Vome component on the home refuses configuration.yaml, secrets.yaml and Home Assistant's database (also through a link with another name), anything outside the config directory, and .storage.
There is no undo, so read the file first if its contents might be wanted, and ask the owner before deleting anything you did not create. If something !includes the file, remove that reference first or Home Assistant will fail its configuration check. Requires the ha:files scope.
Inputs: path (required), instance_id (required).
ha_delete_dashboardDelete Lovelace dashboardADestructive
Delete a storage-mode Lovelace dashboard by its id (from ha_list_dashboards or ha_create_dashboard). Requires HA_ALLOW_WRITE=true and HA_ALLOW_CONFIG_WRITE=true.
Inputs: dashboard_id (required), instance_id.
ha_delete_helperDelete a helperADestructive
Delete a stored Home Assistant helper by id (from ha_list_helpers). The entity disappears immediately, and anything referencing it — automations, dashboards, template sensors — will start reporting an unknown entity, so check what uses it first.
A helper defined in configuration.yaml can be destroyed by this. Stored helpers and YAML helpers share one id namespace and one entity-registry slot, and Home Assistant deletes by that slot. Deleting a stored helper whose id matches a YAML helper's key removes the YAML entity's registry entry as well, and the entity goes with it. Reloading will NOT bring it back — a reload sees an id it already has and changes nothing. Only a full restart recreates the entity. This tool checks for that before deleting and refuses when it finds it; pass confirm_shared_id to go ahead anyway.
An id that is not in ha_list_helpers is refused: a helper defined only in configuration.yaml is removed by editing that file and restarting.
Inputs: kind (required), helper_id (required), instance_id, confirm_shared_id.
ha_delete_scriptDelete scriptADestructive
Delete a script by id. Automations that call it will fail at that step, so remove those calls first. Requires HA_ALLOW_WRITE=true and HA_ALLOW_CONFIG_WRITE=true.
Inputs: script_id (required), instance_id.
ha_delete_userDelete a Home Assistant userADestructive
Permanently delete a user and any login credentials attached to it. Cannot delete the account currently in use (the broker's own owner account) or a system-generated user. Requires ha:config.
Inputs: user_id (required), instance_id.
ha_edit_config_fileEdit part of a config file in placeADestructive
Change part of a text file under the config directory: each edit replaces one exact piece of text with another, and must match exactly once. Prefer this to ha_write_config_file for any change to an existing file: resending a 70 KB file to change three lines is slow and risks a slip anywhere in it. Nothing is written unless every edit applies. Afterwards the configuration is checked and the file put back if the edit broke it, as with ha_write_config_file. Requires the ha:files scope.
Inputs: path (required), edits (required), instance_id (required), verify.
ha_fire_eventFire an eventB
Fire a custom event on the Home Assistant event bus (advanced). Useful for triggering event-based automations during testing. Requires writes to be enabled.
Inputs: event_type (required), event_data, instance_id.
ha_get_automationGet automation configBRead-only
Get the full configuration (triggers, conditions, actions) of an automation. Accepts either the entity_id (automation.xxx) or the unique id.
Inputs: automation (required), instance_id.
ha_get_configGet Home Assistant configARead-only
Return core Home Assistant configuration: version, location name, time zone, unit system and the list of loaded integrations/components. A good first call to understand the instance.
Inputs: instance_id.
ha_get_dashboardGet Lovelace dashboard configARead-only
Get the full Lovelace configuration for one dashboard (views, cards, etc.). Use url_path from ha_list_dashboards — e.g. 'lovelace' for the default overview, or a custom path like 'sam-energy'.
Inputs: url_path, instance_id.
ha_get_entity_registryGet entity registryARead-only
Inspect the entity registry: platform, area, device, unique-id metadata and whether entities are disabled or hidden. Useful for finding disabled entities or the area/device an entity belongs to.
Inputs: domain, entity_id, instance_id, include_disabled.
ha_get_error_logGet error logARead-only
Return the tail of the raw Home Assistant error log. ha_get_system_log is usually the better first stop (grouped and structured); reach for this one when you need the raw ordering, or lines the structured store drops.
Inputs: tail_lines, instance_id.
ha_get_historyGet entity historyARead-only
Get historical state changes for one or more entities over a time window. Times are ISO 8601 (e.g. 2026-06-05T06:00:00+00:00). Defaults to the last day if no start_time is given; with a start_time and no end_time it runs up to now (Home Assistant on its own would stop 24 hours after the start).
Inputs: entity_ids (required), minimal, end_time, max_points, +2 more.
ha_get_logbookGet logbookARead-only
Return human-readable logbook entries (what happened and when), optionally filtered to a single entity and time window. Times are ISO 8601; with a start_time and no end_time it runs up to now (Home Assistant on its own would stop 24 hours after the start).
Inputs: end_time, entity_id, start_time, instance_id.
ha_get_scriptGet script configARead-only
Get a script's full configuration (alias, sequence, fields, mode). List scripts with ha_list_entities domain='script'.
Inputs: script (required), instance_id.
ha_get_stateGet entity stateARead-only
Get the full state and attributes for one or more entities. Use this to read exact current values before changing them or writing template/automation logic.
Inputs: entity_ids (required), instance_id.
ha_get_supervisor_logGet Supervisor / add-on logARead-only
Tail the logs of an add-on, Home Assistant Core, the Supervisor itself, or the host — for problems that never reach HA's own error log (an add-on crash-looping, a failed install, host-level trouble). Requires a Supervised / HAOS install. Works through the VomeHome broker too (read scope).
Inputs: target, addon_slug, tail_lines, instance_id.
ha_get_system_logGet system log (structured)ARead-only
Home Assistant's deduplicated error store: one record per distinct problem, with level, logger, source file:line, occurrence count and first/last seen. Prefer this over ha_get_error_log — 20 grouped issues instead of 200 raw lines. Filter by minimum level, logger name or free text. Full tracebacks are omitted by default (you still get the final exception line); set include_exception=true, usually narrowed with 'contains', to read a whole stack.
Inputs: limit, logger, contains, min_level, +2 more.
ha_get_traceGet automation/script traceARead-only
Step-by-step detail for one run: what triggered it, every condition and action in order with its result, and 'failed_at' naming the first step that errored or evaluated false. This is the tool for 'why didn't my automation run' — logs usually stay silent about a condition returning false. Give 'item' and omit run_id for its most recent run, or give a run_id from ha_list_traces (item is then optional — the run's own item is looked up). Summarised by default; set full=true for the raw trace including the config (large).
Inputs: full, item, domain, run_id, +2 more.
ha_hacs_add_repositoryAdd a custom HACS repositoryADestructive
Add a custom repository to HACS by GitHub 'owner/repo' (or its URL) and category (e.g. 'integration', 'plugin', 'theme', 'python_script', 'appdaemon', 'netdaemon', 'template'). This only registers it with HACS — call ha_hacs_download_repository afterwards to actually install it. Requires ha:config: this is how a repository HACS doesn't already list (a fork, a private project, one not yet in the default store) becomes installable at all.
HACS reports success on this call even when the add silently failed, so this tool confirms by re-listing repositories and checking the new one actually appears.
Inputs: category (required), repository (required), instance_id.
ha_hacs_download_repositoryInstall (download) a HACS repositoryADestructive
Install or update a repository HACS already knows about — this is the step that actually writes its files into the config directory and, for a brand-new integration, reloads HACS's entities. Accepts either the repository id (from ha_hacs_list_repositories or ha_hacs_add_repository) or its 'owner/repo' full name. A newly installed custom integration or add-on domain still needs a Home Assistant restart before it can be set up; a plugin/theme/dashboard resource does not. Requires ha:config.
Inputs: repository (required), version, instance_id.
ha_hacs_infoHACS statusARead-only
Whether HACS is installed and its version, configured country, and whether it has pending background tasks. Returns an error if HACS is not installed on this instance.
Inputs: instance_id.
ha_hacs_list_repositoriesList HACS repositoriesARead-only
List repositories HACS knows about — both custom and default-store ones it has fetched metadata for. Each row includes id, full_name, category, installed, and whether it's custom. Use this to find a repository's id before calling ha_hacs_download_repository or ha_hacs_remove_repository.
Inputs: categories, instance_id.
ha_hacs_remove_repositoryRemove a HACS repositoryADestructive
Uninstall a HACS-managed repository's files and stop HACS tracking it as custom. Accepts either the repository id or its 'owner/repo' full name. Safe to call on a repository that was never installed (it just stops tracking it). Requires ha:config.
Inputs: repository (required), instance_id.
ha_integration_setup_vomeAdd the Vome (vomesync) integrationADestructive
Ensure the Vome custom component is set up as a config entry: start the vomesync config flow and submit defaults (new signing key + default sync.vome.io URLs). Idempotent if an entry already exists. Requires Core restart after the add-on first installed custom_components/vomesync. Needs ha:config.
Inputs: uid, force, instance_id.
ha_list_areasList areasARead-only
List all Home Assistant areas (rooms/zones) with their ids, names and floor. Use the area_id or name to filter other tools.
Inputs: instance_id.
ha_list_automationsList automationsARead-only
List all automations with their entity_id, unique id (needed to read/edit config), on/off state and last triggered time.
Inputs: instance_id.
ha_list_config_entriesList config entries (integrations)BRead-only
List installed Home Assistant config entries (integrations). Optional domain filter, e.g. vomesync.
Inputs: domain, instance_id.
ha_list_config_filesList files in the config directoryARead-only
List a directory under Home Assistant's config directory. Omit 'path' for the root, where configuration.yaml lives.
Requires the ha:files scope, which covers reads as well as writes because these files hold credentials. Home Assistant's internal .storage is never listed.
Inputs: path, instance_id.
ha_list_dashboardsList Lovelace dashboardsARead-only
List Home Assistant Lovelace dashboards (url_path, title, mode, sidebar visibility). Works in direct HA mode and VomeHome brokered mode.
Inputs: instance_id.
ha_list_devicesList devicesARead-only
List Home Assistant devices from the device registry. Optionally filter by area (id or name) and/or a search string matching name, manufacturer or model.
Inputs: area, search, instance_id.
ha_list_discovery_flowsList in-progress (discovered) config flowsARead-only
List config flows Home Assistant has started but not finished — chiefly integrations discovered on the network and waiting to be added. Each row carries the discovery context (host/IP, device id, model, serial) the integration matched on, so this answers 'what has HA found that is not set up yet?'. Optional domain filter.
Inputs: domain, instance_id, include_user_flows.
ha_list_entitiesList entitiesARead-only
List entities with their current state. Filter by domain (e.g. 'light'), a free-text search over entity_id and friendly name, and/or an area (id or name). This is the fastest way to discover what exists before calling services or editing automations.
Inputs: area, limit, domain, search, +2 more.
ha_list_helpersList Home Assistant helpersARead-only
List the helpers Home Assistant stores — input_boolean, input_number, counter, timer and the rest. These are the ones created through the UI (or by ha_set_helper); helpers defined in configuration.yaml are not returned here, because Home Assistant keeps those separately and they cannot be edited at runtime.
They are kept separately but they are NOT independent: both kinds share one id namespace and one entity-registry slot per id. A row listed here can therefore be a phantom whose entity actually belongs to a configuration.yaml helper of the same id — see ha_delete_helper.
Omit 'kind' to list every type. Types: input_boolean, input_number, input_text, input_select, input_datetime, input_button, counter, timer, schedule.
Inputs: kind, instance_id.
ha_list_servicesList servicesARead-only
List callable Home Assistant services. Without a domain, returns every domain and its service names. With a domain, returns that domain's services including their fields/parameters so you know what data to pass to ha_call_service.
Inputs: domain, instance_id.
ha_list_tracesList automation/script tracesARead-only
List recent runs of an automation or script: when it ran, whether it finished, and how it stopped ('failed_condition' means a condition blocked it). Omit 'item' to list runs across everything in the domain. Home Assistant keeps a limited number of traces per item (5 by default), and none from before the last restart.
Inputs: item, limit, domain, instance_id.
ha_list_usersList Home Assistant usersARead-only
List every user on this Home Assistant instance: id, name, username (if they have a local login), role (from group_ids), is_active, is_owner, and whether they're system-generated (Supervisor's internal users — leave those alone).
Inputs: instance_id.
ha_matter_reinterviewRe-interview a Matter deviceA
Ask a Matter device to describe itself again — the device page's Re-interview button. Do this after a firmware update, or when a button, endpoint or feature stopped appearing: Home Assistant only learns about changed endpoints when it asks. A battery device may need waking (press a button) first. Takes the Home Assistant device id from ha_list_devices. Requires HA_ALLOW_CONFIG_WRITE (ha:config).
Inputs: device_id (required), instance_id.
ha_provision_service_loginGive a program its own Home Assistant login, without anyone seeing the passwordADestructive
Create a non-admin Home Assistant login for a program (an MQTT client such as Zigbee2MQTT or an energy manager, an ESPHome device, a bridge), generate its password here, and write it straight into where that program reads it: an add-on's options and/or a secrets file. The password is never returned — not to you and not to the owner — so you never have to choose, see or type one. The Mosquitto add-on accepts Home Assistant logins, so this is all an MQTT client on this home needs.
Ask the owner before calling it: it creates a standing account on their home that outlives the API key that made it. Every delivery target is checked before anything is created; a new login that could be delivered nowhere is deleted again. Use rotate=true to issue a new password to a login this tool created earlier (the old one stops working); it refuses any other account. A program outside Home Assistant with neither add-on options nor a secrets file cannot be reached from here — ask the owner to set its login. Revoke with ha_delete_user. Requires ha:config, plus ha:files for secrets_file targets.
Inputs: name (required), username (required), deliver_to (required), instance_id (required), +3 more.
ha_read_config_fileRead a config fileARead-only
Read a file under Home Assistant's config directory — configuration.yaml, a package, an included YAML file, or (with encoding='base64') a packaged binary asset such as an icon or a data file a custom integration ships.
Read this before writing it: ha_write_config_file replaces the whole file, so the way to add a section is read, append, write back. Requires the ha:files scope.
Inputs: path (required), encoding, instance_id.
ha_reload_automationsReload automationsA
Reload automations from configuration without restarting Home Assistant (calls automation.reload). Requires writes to be enabled.
Inputs: instance_id.
ha_remove_entityRemove an entity from the registryADestructive
Remove an entity's registry entry, for cleaning up orphans: an entity whose integration no longer provides it (status 'unavailable' with restored: true), or one left behind by a deleted device. An entity its integration still provides comes straight back, so disable it with ha_update_entity instead. Requires HA_ALLOW_CONFIG_WRITE (ha:config).
Inputs: entity_id (required), instance_id.
ha_remove_user_credentialsRemove a user's login without deleting the userADestructive
Remove the local username/password login from a user, without deleting the user record itself. The user still exists (and keeps any other login method) but can no longer sign in with this username. Use ha_delete_user to remove the account entirely. Requires ha:config.
Inputs: username (required), instance_id.
ha_render_templateRender a Jinja templateARead-only
Render a Home Assistant Jinja2 template against live state and return the result. Ideal for iterating on template sensors, automation conditions and value_templates until they produce the expected output. Example: "{{ states('sensor.outside_temp') | float < 5 }}".
Inputs: template (required), variables, instance_id.
ha_save_dashboardSave Lovelace dashboard configADestructive
Save (create or replace) the Lovelace configuration for a dashboard. 'config' is the dashboard body (title, views, …). Requires HA_ALLOW_WRITE=true and HA_ALLOW_CONFIG_WRITE=true.
Inputs: config (required), url_path (required), instance_id.
ha_set_automationCreate or update automationADestructive
Create or update an automation by unique id. 'config' is the automation body (alias, trigger, condition, action, mode). Home Assistant reloads automations automatically after saving. Requires HA_ALLOW_WRITE=true and HA_ALLOW_CONFIG_WRITE=true.
Inputs: config (required), automation_id (required), instance_id.
ha_set_helperCreate or update a helperADestructive
Create a Home Assistant helper, or update one that exists. This is how to add a helper without editing configuration.yaml — that file is not reachable from here and would need a restart; a helper created this way is stored by Home Assistant and its entity exists immediately.
Omit 'helper_id' to create; pass the id from ha_list_helpers to update. The new entity is ..
Fields per kind — Home Assistant validates and will name anything wrong: • input_boolean: name; optional icon, initial • input_number: name, min, max; optional step, initial, mode (box|slider), unit_of_measurement, icon • input_text: name; optional min, max, initial, pattern, mode (text|password), icon • input_select: name, options (array of strings); optional initial, icon • input_datetime: name, and at least one of has_date / has_time; optional initial, icon • input_button: name; optional icon • counter: name; optional initial, step, minimum, maximum, restore, icon • timer: name; optional duration (HH:MM:SS), restore, icon • schedule: name; optional monday…sunday (arrays of {from, to}), icon
Inputs: kind (required), config (required), helper_id, instance_id.
ha_set_log_levelSet log levelA
Raise or lower logging for one integration (or several) at runtime, via logger.set_level. Use this before reproducing a problem — debug on one integration, rather than global debug that drowns the log. Bare names are treated as core integrations ('hue' -> homeassistant.components.hue); anything containing a dot is used as-is ('custom_components.vomesync'). Levels reset on restart. Requires HA_ALLOW_WRITE=true in direct mode.
Inputs: level, levels, instance_id, integration.
ha_set_scriptCreate or update scriptADestructive
Create or update a script by id. 'config' is the script body ({ alias, sequence, fields, mode, ... }); Home Assistant reloads scripts after saving. Use it for a step several automations share, then call it from each with action 'script.'. Requires HA_ALLOW_WRITE=true and HA_ALLOW_CONFIG_WRITE=true.
Inputs: config (required), script_id (required), instance_id.
ha_set_user_credentialsGive a user a username and passwordADestructive
Create a local username/password login and attach it to an existing user that has none yet (use ha_create_user first). Fails if that username is already taken, or the user already has a login (use ha_change_user_password instead).
This mints a standing Home Assistant login independent of any VomeHome API key — revoking the key that called this does not revoke the login. Only do this for an account the home's owner actually wants to exist. Requires ha:config.
Inputs: user_id (required), password (required), username (required), instance_id.
ha_supervisor_apiCall Home Assistant Supervisor APIADestructive
Call a Supervisor endpoint through Home Assistant's supervisor/api WebSocket command (e.g. /addons, /store/addons, /store/repositories). Requires a Supervised / HAOS install and ha:config for mutating methods. Use this for add-on store operations.
Inputs: endpoint (required), data, method, instance_id.
ha_trigger_automationTrigger automationA
Manually run an automation's actions now (automation.trigger). Accepts entity_id or unique id. Set skip_condition=false to also evaluate conditions. Requires writes to be enabled.
Inputs: automation (required), instance_id, skip_condition.
ha_update_entityRename, move, disable or hide an entityADestructive
Change an entity's registry entry: its display name, its entity_id, its area, its icon, or whether it is disabled or hidden. Omit a field to leave it alone; pass null for name, area_id or icon to clear it back to the default. Renaming the entity_id does not update automations, scripts or dashboards that use the old one, so check those first (ha_list_automations). Disabling stops the entity being created at all; hiding only keeps it off auto-generated dashboards. Requires HA_ALLOW_CONFIG_WRITE (ha:config).
Inputs: entity_id (required), icon, name, hidden, +4 more.
ha_update_userUpdate a Home Assistant userADestructive
Change a user's name, role, active state, or local-only restriction. Omit a field to leave it unchanged. Setting is_active=false disables sign-in without deleting the account. Cannot modify the owner's active state, or any system-generated (Supervisor) user. Requires ha:config.
Inputs: user_id (required), name, role, is_active, +2 more.
ha_view_snapshotSnapshot of a dashboard viewARead-only
In one call, everything a dashboard view shows: the state and attributes of each entity, each Markdown template rendered, history as a few points per series, and camera stills as small RGB grids. For a client drawing a dashboard (such as a pane in Claude Code); to read a few entities yourself, ha_get_state is simpler. Parts that fail carry an error; the rest still answers. Camera stills need the key's Cameras tick through VomeHome.
Inputs: frames, history, templates, entity_ids, +1 more.
ha_watch_statesWait for state changesARead-only
Wait up to wait_seconds for any of these entities to change, and return what changed: for a client showing live states (a dashboard pane) instead of polling. The first call returns every entity's current state; pass back the returned cursor to get only changes after it. Through VomeHome only (the home's Vome component sends the changes); the key needs ha:read on the home.
Inputs: entity_ids (required), cursor, instance_id, wait_seconds.
ha_write_config_fileWrite a config fileADestructive
Write a file under Home Assistant's config directory. Defaults to UTF-8 text; pass encoding='base64' to write a binary file (an icon, a data file a custom integration ships) — content is then the base64 of the bytes, not the bytes themselves.
This edit is checked and reversible. After the write, Home Assistant's own configuration check runs, and if it fails the previous contents are put straight back — a bad edit cannot leave Home Assistant unable to start. The result says whether it was verified and whether it was rolled back. Editing configuration.yaml this way is the normal, supported route for a home the user has authorised; it is how a hosted install is configured at all, since there is no SSH into one. (check_config only ever validates YAML, so it says nothing about a binary write; verify defaults to off for encoding='base64' for that reason.)
It replaces the entire file — read it first with ha_read_config_file and send back the full content with your change applied, or you will delete everything else in it.
Pass verify=false when writing several files that are only valid together, then call ha_check_config yourself at the end.
A successful write does not apply the change: restart Home Assistant, or reload the relevant domain, for it to take effect.
Requires the ha:files scope. Prefer a purpose-built tool where one exists: helpers via ha_set_helper and automations via ha_set_automation both apply immediately and cannot break startup.
Inputs: path (required), content (required), instance_id (required), verify, +1 more.
nodered_create_flowCreate a Node-RED flow (tab)A
Add a new Node-RED flow (a new tab) with its nodes, leaving existing flows untouched. The 'flow' object should have a 'label' and a 'nodes' array (Node-RED node objects). Requires HA_ALLOW_WRITE=true and HA_ALLOW_CONFIG_WRITE=true. Safer than nodered_set_flows because it cannot disturb other tabs.
Inputs: flow (required), instance_id.
nodered_delete_flowDelete a Node-RED flow (tab)ADestructive
Delete an entire Node-RED flow (one tab) and all of its nodes by id. This cannot be undone from here. Requires HA_ALLOW_WRITE=true and HA_ALLOW_CONFIG_WRITE=true.
Inputs: id (required), instance_id.
nodered_get_flowGet one Node-RED flow (tab)ARead-only
Get a single Node-RED flow (one editor tab) and its nodes by flow id. Use nodered_get_flows first to discover tab ids and labels.
Inputs: id (required), instance_id.
nodered_get_flowsGet Node-RED flowsARead-only
Get the full Node-RED flow configuration (the JSON array of all nodes across every tab) plus the current revision string. Pass that 'rev' back to nodered_set_flows to avoid clobbering a concurrent change. Prefer nodered_get_flow / nodered_update_flow for single-tab edits.
Inputs: instance_id.
nodered_list_nodesList installed Node-RED nodesARead-only
List the installed Node-RED node modules and the node types they provide (the palette). Use this to check which node types are available before writing a flow that references them.
Inputs: instance_id.
nodered_set_flowsReplace ALL Node-RED flowsADestructive
Replace the ENTIRE Node-RED flow configuration and deploy. This overwrites every tab — prefer nodered_create_flow / nodered_update_flow unless you really mean to rewrite everything. Pass the 'rev' from nodered_get_flows to avoid clobbering a concurrent change. deployment_type controls how Node-RED applies it ('full' restarts all flows; 'flows'/'nodes' restart only what changed; 'reload' re-reads from storage). Requires HA_ALLOW_WRITE=true and HA_ALLOW_CONFIG_WRITE=true.
Inputs: flows (required), rev, instance_id, deployment_type.
nodered_update_flowUpdate a Node-RED flow (tab)A
Replace a single Node-RED flow (one tab) and its nodes by id, leaving other tabs untouched. Read it first with nodered_get_flow, edit, then send the whole flow object back. Requires HA_ALLOW_WRITE=true and HA_ALLOW_CONFIG_WRITE=true.
Inputs: id (required), flow (required), instance_id.
vome_health_checkRun a fresh health checkA
Start a fresh Vome health check on this Home Assistant: after fixing findings, this is how the score catches up. It runs at Vome and takes a couple of minutes; the new report replaces the old one, so read it with vome_health_report (its generated_at changes when it lands). On a home not linked to Vome yet, the integration opens a temporary link first (deleted after a day unless someone signs in). Requires write access. It needs the Vome integration (the Vome app in Home Assistant, or Vome from HACS); vome_health_check runs a first check.
Inputs: use_ai, instance_id.
vome_health_reportRead the home's health scoreARead-only
Vome's health score for this Home Assistant, out of 100, with everything its check found: each finding has a severity (warn, advice, info), a title, the evidence, a recommendation and often the exact entities involved — devices flooding the recorder, entities left behind by removed integrations, automations that are off or never run, batteries not reporting, error noise. Use it to see what is wrong with a home and fix it, finding by finding; then vome_health_check re-scores it. It needs the Vome integration (the Vome app in Home Assistant, or Vome from HACS); vome_health_check runs a first check.
Inputs: instance_id.
vomehome_chap_enrolCHAP: turn on monitoringADestructive
Turn on CHAP for an instance: heartbeats and outage alerts. Needed before a standby can be linked.
Inputs: instance_id (required).
vomehome_chap_link_standbyCHAP: link a standbyADestructive
Make another of the user's house installs this home's standby (for a home hosted by Vome: its local fallback). Then call vomehome_chap_pair to pair both and fill the standby. The standby must already be connected to Vome and running the Vome CHAP add-on.
Inputs: install_id (required), instance_id (required).
vomehome_chap_pairCHAP: pair both installsADestructive
Pair both installs with Vome and fill the standby from a one-off backup of the main install, then keep it in step. Takes a few minutes; follow it with vomehome_chap_status.
Inputs: instance_id (required).
vomehome_chap_set_home_addressCHAP: the home's address at homeBDestructive
Set the house-network address (e.g. 192.168.1.15/24) that follows whichever install runs the home, so phones and dashboards need no change after a switch. address=null stops moving it.
Inputs: address (required), instance_id (required).
vomehome_chap_standby_candidatesCHAP standby candidatesARead-only
The user's other house installs, connected to Vome and not in a pair, that could be this home's standby. Use an id from here with vomehome_chap_link_standby.
Inputs: instance_id (required).
vomehome_chap_statusCHAP statusARead-only
How CHAP stands for an instance: whether it is enrolled, its pair (main install, standby, which one runs the home, the kind of pair), whether the two are paired and in step, each part's state as the CHAP page's picture shows it, and actions — what can be done now. Asked of a standby, it says which main install it belongs to.
Inputs: instance_id (required).
vomehome_chap_switchCHAP: switch to the standbyADestructive
Move the home to the standby on purpose (for maintenance): the main install's latest changes go across first, then the standby starts and the main install stops. Pass cancel=true to call off a switch still waiting for the changes. Ask the user before switching a real home.
Inputs: instance_id (required), cancel.
vomehome_chap_switch_backCHAP: switch backADestructive
Move the home back to its main install. By default the standby's changes go back first; now=true switches back at once and leaves anything changed on the standby since its last sync behind — for emergencies only. Ask the user first.
Inputs: instance_id (required), now.
vomehome_chap_unlink_standbyCHAP: stop using the standbyADestructive
Stop using the linked house standby or local fallback. Refused while it is running the home. Its Home Assistant stays stopped until the user starts it.
Inputs: instance_id (required).
vomehome_complete_onboardingFinish the Home Assistant setup wizardA
Finish the outstanding setup-wizard steps on a VomeHome instance, so it opens on a dashboard rather than the wizard. Intended for a home being set up for other people to look at — a demo should not greet a stranger with a setup form. Provisioning deliberately never does this: location and analytics are the owner's choice, so only run it for a home whose setup you are responsible for. Pass core_config to set the location and units first; omit it and Home Assistant keeps what it detected, which is a safer default than a confidently wrong location. Needs ha:config.
Inputs: instance_id (required), core_config.
vomehome_create_guest_linkCreate a guest linkADestructive
Create a non-admin (unless admin=true) Home Assistant user for this instance, plus a one-click login URL for it — self-serve, revocable sharing without handing out the owner's own login. Only works for Vome-hosted instances (not self-hosted/relay ones): minting a token for someone other than the owner needs direct network access to the VM.
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. This 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 — do not point a guest link at one.
The link expires automatically (default 24h, max 30 days) and can be revoked early with vomehome_revoke_guest_link. Treat the returned URL as a secret; do not log it.
Inputs: instance_id (required), admin, dashboard, expires_in.
vomehome_create_instanceCreate VomeHome instanceA
Create a new Home Assistant instance on VomeHome — useful for spinning up a throwaway test/sandbox install. In brokered mode the API key's create scope is authoritative (no local env flags required). Optionally set VOMEHOME_ALLOW_CREATE=false to block creation locally. The creating API key is granted full Home Assistant access on the new instance (ha:read, ha:write, ha:config, ha:files) and it becomes the active target.
Inputs: name (required), timezone.
vomehome_get_instanceGet VomeHome instanceARead-only
Get one VomeHome instance by id, including live status and the Home Assistant URL. Requires VOMEHOME_TOKEN.
Inputs: instance_id (required).
vomehome_get_login_urlGet VomeHome one-click login URLARead-only
Get a one-click login URL that opens your VomeHome Home Assistant already signed in. Present the returned URL to the user as a link to open in a new browser tab/window. The URL embeds a short-lived credential, so treat it as a secret and do not log it. Requires VOMEHOME_TOKEN.
Inputs: instance_id (required).
vomehome_get_onboardingGet Home Assistant setup-wizard stateARead-only
Which Home Assistant setup-wizard steps are still outstanding on a VomeHome instance. A newly provisioned home has its owner account created but the location, analytics and integration steps left for a person to choose, so it shows the wizard instead of a dashboard until they are done. Requires VOMEHOME_TOKEN.
Inputs: instance_id (required).
vomehome_list_guest_linksList guest linksARead-only
List guest links created for this instance, including already-revoked ones (with revoked_at set). Never returns the login URL again — only enough to identify and manage each link.
Inputs: instance_id (required).
vomehome_list_instancesList VomeHome instancesARead-only
List the Home Assistant instances on your VomeHome account, with status, tier, HA URL and (where available) live health. Requires VOMEHOME_TOKEN.
Inputs: no named parameters.
vomehome_reboot_instanceReboot VomeHome instanceADestructive
Reboot a VomeHome Home Assistant instance (reboots the underlying VM). In brokered mode the API key's ha:write (or instances:write) scope is authoritative; an optional local VOMEHOME_INSTANCES write:false only adds a client-side block.
Inputs: instance_id (required).
vomehome_revoke_guest_linkRevoke a guest linkADestructive
Revoke a guest link immediately: deletes its Home Assistant user, which invalidates every credential and token attached to it in one step. Safe to call on an already-revoked link (no-op).
Inputs: link_id (required), instance_id (required).
vomehome_use_instanceSwitch active VomeHome instanceA
Switch which VomeHome instance the Home Assistant tools target. Subsequent ha_* calls (states, services, automations, templates, check_config) operate on this instance, and write/config permission follows that instance's own flags (declared in VOMEHOME_INSTANCES, the default instance, or auto-granted on create). An undeclared but reachable instance inherits the global default, which in brokered mode defers to the API key's server-side scopes.
Inputs: instance_id (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
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.
Maintenance
Related MCP Connectors
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
A TypeScript MCP server for Home Assistant, enabling programmatic management of entities, automati…
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Host any HTTP API as a standard MCP server; auto-distribute to 12+ mainstream agent platforms.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to control and monitor Home Assistant smart home devices through natural language interactions. Supports device control, entity state monitoring, history access, and automation generation with both MCP protocol and standalone HTTP REST API modes.1MIT
- AlicenseNot gradedqualityNot gradedmaintenanceEnables AI agents to control Home Assistant smart home devices via MCP, with zero external dependencies. Supports calling services, getting states, and looking up service parameters.37 npmMIT
- AlicenseBqualityDmaintenanceMCP server for full Home Assistant control, enabling AI agents to manage dashboards, automations, files, apps, entities, and more via REST API, WebSocket, and SSH.66182 npmMIT
- FlicenseNot gradedqualityBmaintenanceConnects LLM coding agents to Home Assistant instances, enabling configuration file management, service calls, template testing, and automation diagnostics via MCP tools.2-