Skip to main content
Glama
home-assistant-mcp

home-assistant-mcp

by Vortitron

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.

License: MIT Reviewed by HOL Guard

Claude Code asked to set two lights to 40% and switch a socket on; the dashboard pane beside it lights them up as the home reports the change.

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

ha_get_config

Core config: version, location, time zone, loaded components.

ha_list_entities

List entities (filter by domain, free-text search, area).

ha_get_state

Full state + attributes for one or more entities.

ha_get_history

Historical state changes over a time window. Given only a start time, it runs up to now (Home Assistant alone stops 24 hours after the start); ha_get_logbook does the same.

ha_list_services

Available services (and their fields for a given domain).

ha_list_areas

Areas (rooms/zones).

ha_list_devices

Device registry (filter by area / search).

ha_get_entity_registry

Registry metadata: platform, area, device, disabled/hidden.

ha_render_template

Render a Jinja2 template against live state.

ha_list_helpers

List stored helpers (input_boolean, input_number, counter, timer, …).

ha_list_automations

Automations with entity_id, unique id, state, last-triggered.

ha_get_automation

Full automation config (triggers/conditions/actions) for an automation made in the editor. One written in a YAML package or included file is named as such, with what to search for to find its file.

ha_check_config

Validate the configuration (Check configuration).

ha_wait_until_running

Wait (up to 120 s) for Home Assistant to finish restarting, checking its core state every 5 s. While it restarts, the other tools say "Home Assistant is restarting (core state: …)" or "not answering — it may be restarting" instead of a raw 502, nginx 404 or WebSocket error. When the home is a CHAP pair's main and its standby is running the home (failover), they say that instead, name the standby and how to reach it (instance_id on the call, or vomehome_use_instance); the CHAP status is asked once per half minute at most, and only for restart-shaped failures.

ha_get_system_log

Deduplicated, structured errors — level, logger, source, count, first/last seen. Start here.

ha_get_error_log

Tail of the raw Home Assistant error log.

ha_get_supervisor_log

Add-on / Core / Supervisor / host logs (HAOS or Supervised).

ha_list_media_files / ha_read_media_file

Read-only look into /media: a saved camera snapshot comes back as an image (needs ha:files, and Vome add-on 0.3.66 / integration 0.9.51 on the home).

ha_camera_image

A camera's current still, as an image the agent can see. Via VomeHome the key needs Cameras ticked.

ha_camera_frame

A camera still decoded and shrunk to a small grid of RGB pixels, for clients that draw pictures in text.

ha_view_snapshot

Everything a dashboard view shows in one call: states, rendered templates, history in few points, camera frames. For dashboard clients.

ha_watch_states

Wait for state changes instead of polling: the home's Vome component sends them as they happen (through VomeHome). Where no component is connected (a hosted home without the Vome add-on, a direct connection) it reads the states every ~3 s for the same wait and answers in the same shape with mode: "polling"; a 401/403 is never papered over.

ha_get_logbook

Human-readable logbook entries, filtered by entity_id, contains (message, name or entity_id), name (e.g. Vome) and domain. At most limit (default 500) come back, the newest, with count_before_limit, truncated and older_entries_end_time to read further back. A window longer than a day is read a day at a time, newest first, stopping as soon as limit entries match (at most 31 days per call), so Home Assistant is never asked for more than 24 hours at once.

ha_get_energy_prefs

The Energy dashboard's setup (grid, solar, battery, gas, water, tracked devices) with the dashboard's own validation.

ha_list_traces

Recent automation/script runs and how each one stopped.

ha_get_trace

Step-by-step detail for one run, with failed_at naming the blocking step.

Home Assistant — write (write-gated)

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

Tool

Description

ha_call_service

Call any service (turn_on, set_temperature, …). A service that can return a response (shell_command's stdout/stderr/returncode, script, weather.get_forecasts …) is asked for it, and it comes back as service_response.

ha_speech_to_text

Run a WAV (16-bit PCM, at most 30 s) through one of the home's speech-to-text engines (stt.*) and get back the words it heard, to test an assistant's hearing without speaking to a device. audio_path reads a local file (npx servers only); audio_base64 sends the bytes (the hosted MCP). Language defaults to the home's own. Engines want 16 kHz mono (ffmpeg -i in.wav -ar 16000 -ac 1 -sample_fmt s16 out.wav). A write because some engines (Vome Hearing, cloud ones) charge per request: needs HA_ALLOW_WRITE / ha:write; not for external homes through VomeHome.

ha_clear_system_log

Empty the structured error store (only needs HA_ALLOW_WRITE).

ha_set_log_level

Change logging for one integration at runtime (only needs HA_ALLOW_WRITE).

ha_set_automation

Create or update an automation (also needs HA_ALLOW_CONFIG_WRITE).

ha_set_helper

Create or update a helper — no configuration.yaml, no restart.

ha_read_config_file

Read a file under the config directory — text by default, or encoding: 'base64' for a binary asset (needs ha:files).

ha_write_config_file

Replace a file under the config directory — text by default, or encoding: 'base64' for a binary asset; checks the config and restores the file if it fails (needs ha:files).

ha_upload_file

Copy a file already on disk (a web page, an image, a package) into the config directory: read from the MCP server's own filesystem, sent as text or base64 as it needs, at most 2 MiB, written and checked like ha_write_config_file. Local (npx) servers only — the hosted MCP can't see your files and answers with the equivalent curl upload (needs ha:files).

ha_delete_config_file

Delete one file under the config directory. Never a directory, and never configuration.yaml, secrets.yaml or Home Assistant's database. Names its target home like a write (needs ha:files, and Vome add-on 0.3.55 / integration 0.9.39 on the home).

ha_edit_config_file

Change part of a text file in place: exact find-and-replace edits that must each match once, then the same check-and-restore as a write. For a three-line change to a large file (needs ha:files).

ha_list_config_files

List a directory under the config directory, folders first: glob filters by name (*.yaml) or path (**/*.html), offset/limit page (default 200), and the reply gives total_entries, total_bytes (this folder's own files, not subfolders) and truncated when the home stopped at its 500-entry cap (needs ha:files).

ha_move_config_file

Move or rename one file under the config directory, creating folders on the way; never overwrites unless asked. Names its target home like a write (needs ha:files, and Vome add-on 0.3.66 / integration 0.9.51).

ha_delete_helper

Delete a stored helper. Refuses when the id looks shared with a configuration.yaml helper, because Home Assistant would take that entity down with it.

ha_delete_automation

Delete an automation (also needs HA_ALLOW_CONFIG_WRITE).

ha_get_script / ha_set_script / ha_delete_script

Scripts by id, the same way as automations: put a step several automations share in one script. Writes need HA_ALLOW_CONFIG_WRITE.

ha_update_entity

Rename, re-id, move, re-icon, disable or hide an entity in the registry (needs HA_ALLOW_CONFIG_WRITE).

ha_update_device

Rename a device, move it to an area, disable it or set its labels (needs HA_ALLOW_CONFIG_WRITE).

ha_expose_entities

List or change what Assist, Alexa and Google Assistant can see and control; listing needs only read (changing needs HA_ALLOW_CONFIG_WRITE).

ha_set_energy_prefs

Change the Energy dashboard's setup; each list passed replaces that list whole, then it is validated (needs HA_ALLOW_CONFIG_WRITE).

ha_get_statistics

Read long-term statistics (what the Energy dashboard draws) per 5 minutes to month; largest_changes lists the biggest buckets, like the Outliers button.

ha_adjust_statistic

Correct one 5-minute bucket of a statistic, by new value or by adjustment, as Developer Tools → Statistics does (needs HA_ALLOW_CONFIG_WRITE).

ha_remove_entity

Remove an orphaned registry entry (needs HA_ALLOW_CONFIG_WRITE).

ha_matter_reinterview

The Matter device page's Re-interview, for a device whose endpoints changed after a firmware update (needs HA_ALLOW_CONFIG_WRITE).

ha_trigger_automation

Manually run an automation now.

ha_reload_automations

Reload automations without restarting.

Lovelace dashboards (direct HA or VomeHome brokered)

Tool

What it does

ha_list_dashboards

List dashboards (url_path, title, mode, sidebar).

ha_get_dashboard

Read one dashboard's full config (views, cards, …).

ha_save_dashboard

Save/replace a dashboard config (needs HA_ALLOW_CONFIG_WRITE).

ha_create_dashboard

Register a new storage-mode dashboard (needs HA_ALLOW_CONFIG_WRITE).

ha_update_dashboard

Change a dashboard's title, icon, sidebar or admin setting, keeping its cards (needs HA_ALLOW_CONFIG_WRITE).

ha_delete_dashboard

Delete a dashboard by id, cards and all (needs HA_ALLOW_CONFIG_WRITE).

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

ESPHome (brokered to a relay-connected HA)

Tool

Description

esphome_dashboard_info

How ESPHome is reached, and whether flashing/logs are available right now.

esphome_list_devices

List dashboard configurations/devices as compact rows (name, friendly name, configuration, address/ip, versions, state); filter (substring of name, friendly name, filename or address/ip), limit (default 50, max 500), full: true for the dashboard's own rows. Says total, matched and truncated; flags configs needing renames.

esphome_list_migrations

ESPHome spellings a config still uses that have been renamed.

esphome_get_config

Read a configuration's YAML.

esphome_save_config

Write a configuration's YAML, whole: for a new file or a large rewrite (write-gated). Inline as yaml, or yaml_path, a file on the MCP's own machine (npx / stdio; UTF-8, at most 2 MiB) so a long config is not pasted into the call. The hosted MCP cannot read your disk and answers with the REST upload into esphome/ instead.

esphome_edit_config

Change part of a configuration in place with exact find-and-replace edits, so a long file is not resent (write-gated). For a large rewrite, use esphome_save_config with yaml_path rather than huge edits.

vome_health_report

Vome's health score for the home and every finding, with severity, evidence, a recommendation and the entities involved.

vome_health_check

Run a fresh health check, to re-score after fixes (write-gated).

esphome_validate

Validate a configuration.

esphome_compile

Compile firmware.

esphome_upload

Compile + flash a device over the air; validates first (write-gated).

esphome_logs

Read a device's live logs — boot, wifi, sensors, crashes.

esphome_clean

Delete cached build files after a stale-build compile failure (write-gated).

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

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

Node-RED (NODERED_URL)

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

Tool

Description

nodered_get_flows

Get the full flow config (all tabs) plus the current revision.

nodered_get_flow

Get one flow (tab) and its nodes by id.

nodered_list_nodes

List installed node modules/types (the palette).

nodered_create_flow

Add a new tab without disturbing existing flows (write-gated).

nodered_update_flow

Replace one tab by id, leaving others untouched (write-gated).

nodered_delete_flow

Delete a tab and its nodes (write-gated).

nodered_set_flows

Replace the entire flow config and deploy (write-gated).

VomeHome (require VOMEHOME_TOKEN)

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

Tool

Description

vomehome_list_instances

List your HA instances with kind (hosted, relay, external), status, tier, URL, live health, the active instance and per-instance client write/config access. One the portal cannot reach right now (a disconnected relay, a retired home) is marked offline: true with a note.

vomehome_get_instance

Details + live status for one instance.

vomehome_use_instance

Switch which instance the ha_* tools target (multi-instance — see Several instances from one token).

vomehome_reboot_instance

Reboot an instance's VM (write-gated).

vomehome_create_instance

Create a throwaway test/sandbox instance (needs the create scope on your API key; the creating key is granted full HA access on the new instance, which becomes the active target).

vomehome_get_login_url

Mint a one-click HA login URL to open in a new tab.

vomehome_list_backups

Backups in the home's Vome backup location (needs ha:files).

vomehome_backup_download_link

A link to download one backup's .tar, good for about 15 minutes (needs ha:files).

vomehome_create_guest_link

Create a non-admin HA user + one-click login URL for sharing (needs HA_ALLOW_CONFIG_WRITE). Vome-hosted instances only.

vomehome_list_guest_links

List guest links for an instance, revoked ones included.

vomehome_revoke_guest_link

Revoke a guest link immediately.

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

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

Integrations & config entries

Tool

Description

ha_list_config_entries

List installed integrations (config entries). Optional domain filter.

ha_delete_config_entry

Delete a config entry by id — the fix for an orphaned/duplicate entry left behind after a device was removed, which is otherwise why a re-added device's entities pick up a _2 suffix. Needs HA_ALLOW_CONFIG_WRITE.

ha_list_discovery_flows

List integrations Home Assistant has discovered on the network but not yet added.

ha_config_flow

Start (handler), reconfigure an existing entry (entry_id) or continue (flow_id + user_input) an integration's config flow. Needs HA_ALLOW_CONFIG_WRITE.

ha_config_entry_options

Read or set an integration's options — including ESPHome's allow_service_calls.

ha_integration_setup_vome

Add the Vome (vomesync) config entry with default settings, idempotently.

Supervisor / Vome add-on (HAOS / Supervised)

Tool

Description

ha_supervisor_api

Call a Supervisor endpoint via supervisor/api (store, add-ons, …). A …/logs read is served from the log route, since supervisor/api cannot carry plain text, and add-on start/stop/restart wait 50 s instead of Home Assistant's 10.

ha_addon_install_vome

Add https://github.com/Vortitron/VomeSync to the store, install Vome, and start it.

Community store: the Marketplace (2026.11+) or HACS

The ha_hacs_* names predate Home Assistant 2026.11, which built HACS into Core as the Marketplace. Each tool asks marketplace/info first and uses the Marketplace's own commands when it is there, falling back to HACS's hacs/* on older Home Assistants. The names stayed so existing permission rules and prompts keep working.

Tool

Description

ha_hacs_info

Which store this home has (marketplace or hacs) and its status; for the Marketplace, whether GitHub is connected and whether an admin has accepted its warning.

ha_hacs_list_repositories

List repositories the store knows about. Installed ones only by default, trimmed to id, name, category, installed/available version and pending_update; installed_only: false or search looks through the catalogue, categories and limit (default 100) narrow it, full: true returns raw rows.

ha_hacs_add_repository

Add a custom repository by owner/repo and category. The Marketplace only adds one once GitHub is connected in Settings → Marketplace. Confirms by re-listing, since HACS acks even a failed add. Needs ha:config (HA_ALLOW_CONFIG_WRITE in direct mode).

ha_hacs_download_repository

Install (or update) a tracked repository — the step that actually writes its files. Needs ha:config (HA_ALLOW_CONFIG_WRITE in direct mode).

ha_hacs_remove_repository

Uninstall a repository's files and stop tracking it. Needs ha:config (HA_ALLOW_CONFIG_WRITE in direct mode).

There is no REST API or service call for managing repositories — these go over the store's WebSocket commands, the same way as the Supervisor tools above. Adding a repository only registers it; call ha_hacs_download_repository afterwards to install it. With HACS, restart Home Assistant before setting up a new integration; the Marketplace loads a first install straight away and raises a repair when an update needs a restart. Nothing installs through the Marketplace until an admin has accepted its warning in Settings → Marketplace, and there is deliberately no tool for that.

People

Tool

Description

ha_list_people

List the people (Settings → People): linked user, device trackers, and whether each can be edited here (not if defined in configuration.yaml).

ha_set_person

Create or change a person: name, linked user, picture and device trackers. add_device_trackers / remove_device_trackers swap one tracker at a time, such as an old phone for a new one. Needs HA_ALLOW_CONFIG_WRITE.

ha_delete_person

Delete a person; its user and trackers stay. Needs HA_ALLOW_CONFIG_WRITE.

Users

Tool

Description

ha_list_users

List every user: id, name, username, role, active/owner status.

ha_create_user

Create a user with a role (admin / user / read_only) but no login yet. Needs HA_ALLOW_CONFIG_WRITE.

ha_update_user

Change a user's name, role, active state, or local-only restriction. Needs HA_ALLOW_CONFIG_WRITE.

ha_delete_user

Permanently delete a user and its login. Needs HA_ALLOW_CONFIG_WRITE.

ha_set_user_credentials

Give a user with no login yet a username/password. Needs HA_ALLOW_CONFIG_WRITE.

ha_change_user_password

Reset the password for a user that already has a login. Needs HA_ALLOW_CONFIG_WRITE.

ha_remove_user_credentials

Remove a login without deleting the user. Needs HA_ALLOW_CONFIG_WRITE.

ha_provision_service_login

Give a program (an MQTT client, a Zigbee bridge, an ESPHome device) its own non-admin login and write the password straight into its add-on options or a secrets file. The password is generated here and never returned. Needs HA_ALLOW_CONFIG_WRITE, plus ha:files for secrets files.

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

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

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

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

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


Install

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

One‑click (Cursor)

Add to Cursor

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

One‑line config

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

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

Verify / from source

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

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

LAN TCP tunnels (RDP, etc.)

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

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


Configuration

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

Variable

Default

Description

HA_URL

— (required)

Base URL, e.g. http://homeassistant.local:8123.

HA_TOKEN

— (required)

Long-lived access token (Profile → Security).

HA_ALLOW_WRITE

off (direct) / permissive (brokered)

Local write guard. In brokered mode the API key's per-instance scope decides (server-enforced); setting false only adds a local restriction. In direct mode this is the master switch and defaults off.

HA_DENY_DOMAINS

lock,alarm_control_panel,cover,valve,camera (direct) / empty (brokered)

Domains that can never be written. In brokered mode the API key's Sensitive devices setting decides, server-side; set this only to add a local restriction.

HA_ALLOW_DOMAINS

(any)

If set, only these domains may be written.

HA_ALLOW_CONFIG_WRITE

off (direct) / permissive (brokered)

Local guard for editing automation config. Same semantics as HA_ALLOW_WRITE.

NODERED_URL

(disabled)

Node-RED editor/admin base URL, e.g. http://homeassistant.local:1880. Enables the nodered_* tools.

NODERED_TOKEN

—

Bearer token if Node-RED adminAuth is enabled.

NODERED_USERNAME / NODERED_PASSWORD

—

Credentials exchanged for a token via /auth/token, if you prefer not to mint one by hand.

VOMEHOME_API_URL

https://vome.io

VomeHome portal base URL.

VOMEHOME_TOKEN

(disabled)

VomeHome personal access token; enables the vomehome_* tools.

VOMEHOME_INSTANCE_ID

(direct mode)

The active/default instance to broker HA calls to. With a token and no HA_TOKEN, HA tools route through VomeHome (see Brokered mode). What it may do is set by your token's per-instance scopes in the portal (server-enforced).

VOMEHOME_INSTANCES

(none)

Optional JSON registry to make multiple instances known at startup, e.g. [{"id":"rly-house","label":"home"},{"id":"sbx"}]. Per-instance write/config here are optional local restrictions (omit to defer to the server). Switch between them with vomehome_use_instance. See Several instances from one token.

VOMEHOME_ALLOW_CREATE

(defer to key)

Optional local guard for creating an instance. The real authority is the account-wide create scope on your API key; set false to block creation locally regardless. Instances you create are granted full HA access on that key and become the active target for the session.

HA_TIMEOUT_MS

15000

HTTP/WebSocket request timeout.

MAX_RESULTS

500

Max items a list tool returns before truncating.

LOG_LEVEL

info

error | warn | info | debug (logs go to stderr).

Getting a token

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


Editor setup

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

Cursor

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

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

VS Code

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

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

Claude Desktop

Add the same block under mcpServers in claude_desktop_config.json.

Claude Code: the side panes

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

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

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

The automation pane: the automation as a WHEN/THEN map, each step marked by whether its latest run reached it.

The vome-automation pane shows the automation Claude is working on, what a save changed and which steps the latest run took:

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

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

For the home's health, vome-health shows Vome's score and what its check found, marked as Claude fixes each, and re-scored with a roll and fireworks:

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

For a dashboard that works, vome-dash puts one of yours in a pane: live states, controls that switch and dim, cameras in half blocks, and the cards Claude changes lit up:

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

For ESPHome, vome-esphome adds a pane with a map of the device Claude is working on, drawn from its YAML, and the build it runs as it happens:

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

And for fun, vome-doom is house.wad in a pane: your home as a Doom level, where shooting a lamp turns it off for real:

/plugin install vome-doom --marketplace Vortitron/home-assistant-mcp

And just for fun, dont-panic adds the Guide: a pane that animates whatever the agent is doing and files a live, irreverent Guide entry on it. Its README has the price levels; /guide canned costs nothing:

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

To connect Claude Code to a home through Vome without any of the config above, install vome-connect from the same marketplace; it asks for one key, which the Vome app's Agent tab in Home Assistant gives you without signing up:

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

Multiple Home Assistants

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

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

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

Several instances from one token

Name the home on any call. Every tool except the vomehome_* ones accepts an optional instance_id, 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_ID is the active/default instance the ha_* tools target at startup (folded into the registry automatically as "default"). What it may do is set by your token's per-instance scopes in the portal.

  • VOMEHOME_INSTANCES declares which instances are known at startup. Listing them is optional — the token already reaches them — but it lets you pin the active target and add local restrictions. A per-instance write / config here is an optional local-only restriction: omit it to defer to the server, or set false to keep an instance read-only on this machine regardless of what the key allows (the example locks the house locally).

  • vomehome_use_instance switches the active instance for subsequent ha_* calls; vomehome_list_instances shows which one is active and each instance's effective access.

  • Creating instances (vomehome_create_instance) needs the create scope on your key — you own what you create. The portal grants the creating key full Home Assistant access on the new instance (ha:read, ha:write, ha:config, ha:files) so ha_* tools work without a trip back to the tokens page. Other keys, and other homes, stay as you ticked them. The instance also becomes the active target for the session. Add its id to VOMEHOME_INSTANCES to keep it known across restarts.

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

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

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

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

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 doctor

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


Safety

Designed to be safe to point at a real home:

  1. Read-only by default (direct mode). With a raw HA_TOKEN the MCP is the only guard, so every state-changing tool refuses until HA_ALLOW_WRITE=true. In brokered mode permissions instead live on your VomeHome API key and are enforced server-side per instance (see Brokered mode).

  2. Domain deny-list. Even with writes on, sensitive domains (locks, alarms, covers, valves, cameras) are blocked. In direct mode remove them from HA_DENY_DOMAINS; in brokered mode tick them for the key under Sensitive devices on the VomeHome API tokens page.

  3. Optional allow-list. Set HA_ALLOW_DOMAINS to permit only specific domains.

  4. Cross-domain guard. ha_call_service checks the domain of every target entity — including entity ids nested anywhere inside data — so a generic service (e.g. homeassistant.turn_on) cannot be used to reach a denied domain. Generic services targeting an area/device/label are refused while a deny/allow-list is active, because those selectors resolve server-side and cannot be checked here; target entity ids or use the domain-specific service (e.g. light.turn_on) instead.

  5. Separate config-write scope. Editing automation YAML needs its own ha:config scope (brokered) or HA_ALLOW_CONFIG_WRITE=true (direct).

  6. VomeHome guards. Rebooting or creating an instance is gated by the matching scope on your API key (server-enforced); the optional VOMEHOME_ALLOW_CREATE client flag can add a local block. The VomeHome token is scoped server-side to your own account.

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

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

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

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


Brokered mode (the real boundary)

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

  • keeps the HA credential server‑side (the agent never sees it);

  • enforces read / write / config per token, per instance — a token without ha:write for an instance genuinely cannot change it, no matter how it's used;

  • blocks sensitive domains (locks, alarms, …) server‑side, including via generic services (homeassistant.turn_on can't reach a lock);

  • audits every call (allowed or denied) against the token that made it.

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

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

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

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

Brokered mode proxies the everyday loop — list/get entities, list services, call services, read config, render templates — plus automation editing: ha_get_automation, ha_set_automation, ha_delete_automation and ha_check_config. Lovelace dashboards are brokered too: ha_list_dashboards, ha_get_dashboard, ha_save_dashboard, ha_create_dashboard, ha_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 (domain light, area living room).

  • "Make this template return true only after sunset" → iterate with ha_render_template.

  • "Turn the porch light to 30%" → ha_call_service (light.turn_on, brightness_pct: 30). Requires writes enabled.

  • "Fix my morning automation" → ha_get_automation → edit → ha_set_automation → ha_check_config → ha_trigger_automation.

  • "Add a sensor to this ESPHome node and flash it" → esphome_get_config → esphome_edit_config (or esphome_save_config for a new file) → esphome_validate → esphome_upload.

  • "Tidy up my Node-RED 'Heating' tab" → nodered_get_flows (find the tab id) → nodered_get_flow → edit the nodes → nodered_update_flow.

  • "Spin up a sandbox and open it" → vomehome_create_instance → vomehome_get_instance (poll status) → vomehome_get_login_url (open the link).

  • "Why is my Hue integration throwing errors?" → ha_get_system_log (logger: "hue") → read exception_summary → ha_get_system_log again with include_exception: true for the full stack.

  • "Why didn't my morning automation run?" → ha_get_trace (item: "automation.morning") → read failed_at.


Debugging with logs

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

Question

Tool

What is broken right now?

ha_get_system_log

Why didn't this automation do anything?

ha_get_trace

What did the add-on / host do?

ha_get_supervisor_log

What happened to this entity, and when?

ha_get_logbook / ha_get_history

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

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

  1. ha_set_log_level (integration: "hue", level: "debug") — debug on the one integration, not globally.

  2. ha_clear_system_log.

  3. Reproduce it (ha_call_service, ha_trigger_automation, …).

  4. ha_get_system_log — everything returned was caused by step 3.

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

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


ESPHome notes

  • REST endpoints (/devices, /edit) are used for listing and reading/writing YAML. These work over the VomeHome relay as well as directly.

  • validate, compile, upload, logs and clean run over the dashboard's multiplexed /ws API. Over the relay they are brokered as jobs: the portal starts one and this client polls it, which is what lets a multi-minute compile survive the ordinary HTTP timeouts in between.

  • The Vome component owns the dashboard protocol. ESPHome split its dashboard into esphome-device-builder, which replaced the per-command WebSockets (/validate, /logs, …) and the /edit REST endpoint with a single /ws socket; the remaining legacy endpoints are documented upstream as deprecated. The component translates /ws into the stable line/exit stream the relay carries, so this client, the portal and the relay never learn that ESPHome moved. Builds go through the dashboard's job queue, so an agent-triggered build also shows up in its own "Firmware tasks" panel.

  • Requires the Vome add-on at 0.3.30 or later. Older components speak a protocol the dashboard no longer answers; the error says so and names the version rather than blaming ESPHome.

  • The relay is preferred over reaching the dashboard directly, even when both would work. Going direct skips the portal's per-instance scope checks and its audit log — a revoked token would still be able to flash a device that happened to share a network with the agent. It is also the only route that works on a default HAOS install, where the add-on's web port is disabled and its ingress admits only the Supervisor and localhost.

  • Discovery (src/esphome/discovery.ts) finds a dashboard for direct mode, where there is no relay and so no policy layer to bypass. Call esphome_dashboard_info to see which mode is active and, when nothing is reachable, every address that was tried and how each failed.

  • The dashboard authorises WebSocket commands with its own cookie/XSRF when a dashboard password is set, so these commands work against password-less dashboards or ones reachable on a trusted network / behind an auth-terminating proxy. Token/basic auth here only helps for the latter.

  • esphome_upload validates before it flashes. A device that takes a bad build is offline until someone reaches it with a cable, so the cheap check runs first; pass skip_validate: true to bypass it.


Node-RED notes

  • The HA Node-RED add-on exposes the editor on port 1880 (http://homeassistant.local:1880). Point NODERED_URL at it.

  • If the add-on has a credential secret / adminAuth set, supply NODERED_TOKEN (or NODERED_USERNAME/NODERED_PASSWORD, which the client exchanges for a token). An add-on reachable only on your trusted network, or behind HA ingress / an auth-terminating proxy, needs no auth here.

  • nodered_set_flows rewrites everything — prefer nodered_create_flow / nodered_update_flow for day-to-day edits. Pass the rev from nodered_get_flows so a concurrent change in the editor is detected rather than silently overwritten.

  • Node-RED flows are plain JSON, which makes them a natural target for alternative front-ends (PLC-style ladder, Scratch/Blockly). That exploration lives in the VomeHome repo (docs/alt_interfaces_plan.md).

Development

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

Layout:

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

Roadmap

  • VomeHome‑brokered HA access (the real boundary) — shipped (MVP). HA reads/writes can be proxied through VomeHome with a revocable VOMEHOME_TOKEN so the HA credential never reaches the agent and the read‑only / deny‑domain / audit policy is enforced server‑side. Automation editing and the ESPHome REST subset are brokered too (the latter over a relay-connected HA). See Brokered mode. Next: registry (areas/devices) over the broker and a per‑token audit view in the portal.

  • VomeHome test installs. The vomehome_* tools already list, create, reboot and open instances. Next: point HA_URL/HA_TOKEN at a freshly created sandbox automatically so an agent can try changes there before touching a real home, then promote what works. (Requires the portal API endpoints described in project_outline.md.)

  • ESPHome over the relay — shipped. Builds, flashing and device logs are brokered as polled jobs, so a remote agent can flash hardware with no inbound exposure and with scope checks and audit in front of every command. Next: device adoption (the /import + wizard flow), so an agent can take a brand-new board from unflashed to working entity without a UI step.

  • Node-RED — flow read/write/deploy shipped. Next: brokering the admin API through VomeHome (as HA and the ESPHome REST subset already are) so a relay-connected home needs no directly-reachable Node-RED URL, and a flow diff/validate step before deploy.

  • MCP resources for entities/areas (in addition to tools).

  • Optional HTTP/SSE transport for remote use.


License

MIT © Vortitron

Available Tools

111 tools
esphome_activityESPHome build activityA
Read-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 filesA
Destructive

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 capabilityA
Read-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 configA
Destructive

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 configB
Read-only

Read the YAML for an ESPHome configuration file (e.g. 'living-room.yaml').

Inputs: configuration (required), instance_id.

esphome_list_devicesList ESPHome devicesA
Read-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 renamesA
Read-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 logsA
Read-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 configA
Destructive

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)A
Destructive

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 configA
Read-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-onA
Destructive

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 serviceA
Destructive

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 pixelsA
Read-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 cameraA
Read-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 passwordA
Destructive

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 configurationA
Read-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 logA
Destructive

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 optionsA
Destructive

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 flowA
Destructive

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 userA
Destructive

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 automationA
Destructive

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)A
Destructive

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 directoryA
Destructive

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 dashboardA
Destructive

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 helperA
Destructive

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 scriptA
Destructive

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 userA
Destructive

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 placeA
Destructive

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 configB
Read-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 configA
Read-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 configA
Read-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 registryA
Read-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 logA
Read-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 historyA
Read-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 logbookA
Read-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 configA
Read-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 stateA
Read-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 logA
Read-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)A
Read-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 traceA
Read-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 repositoryA
Destructive

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 repositoryA
Destructive

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 statusA
Read-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 repositoriesA
Read-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 repositoryA
Destructive

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) integrationA
Destructive

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 areasA
Read-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 automationsA
Read-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)B
Read-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 directoryA
Read-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 dashboardsA
Read-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 devicesA
Read-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 flowsA
Read-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 entitiesA
Read-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 helpersA
Read-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 servicesA
Read-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 tracesA
Read-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 usersA
Read-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 passwordA
Destructive

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 fileA
Read-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 registryA
Destructive

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 userA
Destructive

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 templateA
Read-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 configA
Destructive

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 automationA
Destructive

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 helperA
Destructive

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 scriptA
Destructive

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 passwordA
Destructive

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 APIA
Destructive

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 entityA
Destructive

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 userA
Destructive

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 viewA
Read-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 changesA
Read-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 fileA
Destructive

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)A
Destructive

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)A
Read-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 flowsA
Read-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 nodesA
Read-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 flowsA
Destructive

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 scoreA
Read-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 monitoringA
Destructive

Turn on CHAP for an instance: heartbeats and outage alerts. Needed before a standby can be linked.

Inputs: instance_id (required).

vomehome_chap_pairCHAP: pair both installsA
Destructive

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 homeB
Destructive

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 candidatesA
Read-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 statusA
Read-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 standbyA
Destructive

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 backA
Destructive

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_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_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 instanceA
Read-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 URLA
Read-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 stateA
Read-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_instancesList VomeHome instancesA
Read-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 instanceA
Destructive

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

    A3.6/5.0

    Scored across 111 tools

    Disambiguation3/5

    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.

    Naming Consistency4/5

    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.

    Tool Count1/5

    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.

    Completeness4/5

    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

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      MCP server for full Home Assistant control, enabling AI agents to manage dashboards, automations, files, apps, entities, and more via REST API, WebSocket, and SSH.
      66
      182 npm
      MIT
    • F
      license
      Not graded
      quality
      B
      maintenance
      Connects LLM coding agents to Home Assistant instances, enabling configuration file management, service calls, template testing, and automation diagnostics via MCP tools.
      2
      -