ha-dev-tools MCP server
Commit Oct 31, 2026Enables AI coding assistants to manage Home Assistant automations, entities, dashboards, and helpers through a secure, propose-and-confirm workflow.
Also known as alexlenk/ha-dev-tools
- Stars
- 3
- Tools
- 34
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Oct 31, 2026
- License
- MIT
What is ha-dev-tools MCP?
ha-dev-tools enables AI coding assistants to manage Home Assistant automations, entities, dashboards, and helpers through a secure, propose-and-confirm workflow. It exposes 34 tools, such as find_entities, describe_entity, render_template.
Summary generated from the project's README
About ha-dev-tools MCP server
Managing Home Assistant configurations through an AI coding assistant is what ha-dev-tools enables for smart home enthusiasts and developers. This remote MCP server runs directly inside your Home Assistant instance using the built-in mcp_server integration, meaning you do not need to host a separate service. It provides an interface for tools like Claude Code or Cursor to interact with your automations, entities, dashboards, and scripts using a long-lived access token for authentication.
Safety is a core component of the workflow, as every modification requires a two-step propose-and-confirm process. Users can also enable an optional dry-run mode to preview changes without applying them to the live system, or use git mirroring to maintain a history of all modifications. To perform write operations, the server must be armed via a filesystem command to prove administrative access, which remains active for a configurable period of time.
What you can do with it
- 1Create new smart home automationsAsk your AI assistant to write a new automation that triggers based on specific sensor states or time of day.
- 2Debug automation and sensor issuesUse the assistant to investigate why a specific device failed to trigger or to check the logs for errors.
- 3Maintain and clean up entitiesIdentify and remove leftover entities from devices that have been removed from your smart home setup.
Written from the project's README. Every use case is checked against a quote from it.
ha-dev-tools MCP tools 34
Detected from the READMEfind_entitiesdescribe_entityrender_templatevalidate_templateget_automationwrite_automationdelete_automationcheck_configget_config_filereload_domaindelete_entitydelete_entities
Show all 34 toolsShow fewer tools
update_entitieslist_dashboardspatch_dashboardwrite_customizedelete_packagetrigger_automationset_automation_enabledset_valueset_number_valueset_boolean_valuecontrol_entitiesget_logsget_entity_historyget_logbookmerge_statisticsderive_statisticsredistribute_statisticswrite_statisticsrestore_statisticslist_mqtt_topicsentity_health_reportaudit_automations
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablealexlenk/ha-dev-tools is public and reachablegithub.com/alexlenk/ha-dev-tools ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-31github.com/alexlenk/ha-dev-tools ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model34 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubDev Tools MCP
[![GitHub Release][releases-shield]][releases] [![GitHub Activity][commits-shield]][commits] [![codecov][codecov-shield]][codecov] ![License][license-shield] [![hacs][hacsbadge]][hacs]
An MCP server for Home Assistant that runs inside Home Assistant itself - it gives your AI coding assistant (Claude Code, Cursor, Codex, or any other MCP client) hands-on access to your instance, the same way it already helps you with code, but for automations, entities, dashboards, and helpers.
It runs inside Home Assistant's own mcp_server
integration, so there's
no separate server to install, host, or keep running - just a Bearer token
and an MCP client. And because handing write access to an AI assistant is a
big ask, every write is proposed and previewed before anything happens, an
optional dry-run mode can keep it that way permanently, and optional git
mirroring gives you a private, before/after history to roll back from by
hand. See The safety model below for exactly what that
does and doesn't guarantee - it's worth reading before you turn this loose on
a live instance.
What you can ask it to do
- "Add an automation that turns on the hallway light when the hallway motion sensor trips after sunset."
- "Find every automation that references an entity that's now unavailable."
- "The porch light didn't turn on last night - check the logs and logbook and tell me why."
- "Clean up the 40 leftover entities from the Zigbee device I just removed."
⚠️ Use at your own risk. This is a community project, built and maintained in spare time - no SLA, no guaranteed support, and no guarantee that dry-run, the confirm step, or git mirroring catch every mistake before it reaches your live instance. AI can be wrong, and this is all still a work in progress. Provided as-is, with no warranty - see LICENSE.
Quick start
Needs Home Assistant 2026.10.0+ (see Requirements below for the full list, including client-specific versions).
-
Install via HACS or manually - see Installation below.
-
Settings → Devices & Services → Add Integration → Dev Tools MCP.
-
Settings → Devices & Services → Add Integration → Model Context Protocol Server (Home Assistant's own built-in integration) - in its setup, add
dev_toolsto the exposed APIs. This step is easy to miss and is the single most common way to end up stuck: skip it and Dev Tools MCP's card still shows healthy, but an MCP client just gets a bare 404 (a Settings → System → Repairs issue will flag it if you do). -
Arm it. Every tool except a diagnostic ping refuses to run until you prove real filesystem access - the same kind SSH or the Terminal add-on already requires:
date +%s > /config/.storage/ha_dev_tools.armedThis enables
dev_toolsfor up to 4 hours (extended by 30 minutes each time a tool is used, and it expires on its own after 30 minutes idle). Both limits can be changed on the integration's Configure page (idle window 5 minutes - 8 hours, hard cap 15 minutes - 24 hours). Since it expires, a shell alias saves retyping it:echo 'alias dev-tools-arm="date +%s > /config/.storage/ha_dev_tools.armed && echo armed"' >> ~/.bashrc && source ~/.bashrc -
Connect your MCP client to
https://<your-ha-instance>/api/mcp/dev_tools, authenticated with a normal Home Assistant admin long-lived access token as a Bearer token. For Claude Code:claude mcp add --transport http ha-dev-tools \ https://<your-ha-instance>/api/mcp/dev_tools \ --header "Authorization: Bearer <your-long-lived-access-token>" \ --scope userSee Connecting an MCP client below for other clients, and why Claude Desktop/claude.ai generally can't be pointed at a home LAN instance directly.
That's it - ask it something.
The safety model
Every write tool (write_automation, delete_automation, write_script,
the helper/derived-sensor/template-entity CRUD tools, delete_entity/
delete_entities, write_dashboard/patch_dashboard, write_energy_config,
write_rest_command, the package platform-entry tools, write_customize,
set_automation_enabled, control_entities) always requires
two calls: propose
(no arguments changed, no side effects - returns a preview of what would be
applied plus a short-lived confirm_token) and confirm (the identical
call, plus that token - only this one can actually do anything). That's
always on and can't be turned off. Two optional layers sit on top of it.
Here's exactly what each one actually guarantees:
| Layer | Guarantee | What it's for |
|---|---|---|
| Confirm step (always on) | UX friction, not an enforced human check - nothing stops an agent from calling propose then confirm back to back with no one actually reading the preview in between | Catches accidental first-call writes and stops a token from silently being reused for a different call |
| Dry-run mode (optional) | Hard guarantee - a confirmed write's content is resolved but never reaches disk while it's on | Lets you review an agent's proposed changes for as long as you want, with zero risk of any of them going live |
| Git mirroring (optional) | Audit trail only - it never gates a write, live or dry-run | A private, before/after history of every change, so you have something to manually restore from (copy the old YAML back) if something goes wrong |
In short: dry-run is the actual safety net. The confirm step and git mirroring make mistakes easier to catch and easier to undo, but neither one stops a bad write from happening. If you want a real guarantee that nothing touches your live config while you're still trusting an agent, turn dry-run on and read what it proposes.
See Setup below for how to enable each, and docs/SECURITY.md for the full threat model - including what these gates do not protect against (this integration isn't sandboxed; a confirmed, non-dry-run write has the same power as your admin account, full stop).
Requirements
- Home Assistant 2026.10.0 or newer - the first release whose tool API
has
ToolResultand tool annotations (issue #152; returning plain JSON stops working in 2027.11). The nativemcp_serverintegration this depends on shipped earlier; HA itself requires Python 3.14.2+. - The
mcp_serverintegration, configured to expose thedev_toolsAPI (see Quick start above). - If connecting with Claude Code, Claude Code 2.1 or newer - it's the
release line that correctly prioritizes a configured Bearer token over
mcp_server's OAuth discovery metadata. Runclaude updateif unsure.
Installation
HACS (recommended)
- Open HACS and search for Dev Tools MCP (called HA Dev Tools MCP before 2.34.0; it's in the default HACS list, so no custom repository is needed).
- Download it.
- Restart Home Assistant.
Manual
- Download the latest release.
- Copy the
ha_dev_toolsfolder into<config>/custom_components/. - Restart Home Assistant.
Connecting an MCP client
This integration is a remote MCP server - Home Assistant's own mcp_server
integration serves it over Streamable HTTP at
https://<your-ha-instance>/api/mcp/dev_tools, authenticated with a Bearer
token (a normal Home Assistant admin long-lived access token, created under
your HA profile's Security tab). It is not a local/stdio server, so it
doesn't go through claude_desktop_config.json-style local server setup - and
the token, not OAuth, is the auth mechanism actually meant to be used here,
even though mcp_server also advertises OAuth discovery metadata (RFC 9728)
alongside it, for web-based clients that require it. That advertisement
matters for setup, covered below.
-
Claude Code (CLI, 2.1+ - see Requirements) supports remote HTTP servers with custom headers directly, so a Bearer token works as-is (see the command in Quick start above). Run
claude mcp listafterward to confirm it shows as connected. -
Claude Desktop and claude.ai connect to remote servers only through Settings → Connectors → Add custom connector, which has two problems for a typical home HA setup, not just one:
- That flow is built around OAuth - there's no field in it for a static
Bearer token or API key for an individual account. (An org-admin
static_headersconnector option exists on some plans and can carry a fixedAuthorizationheader instead, but that's not available to a regular Pro account.) - Separately, the connector doesn't connect from your Desktop app's own
network the way a local/stdio server would - it's opened from Anthropic's
cloud infrastructure. So the URL also has to be reachable on the public
internet over HTTPS with a valid (non-self-signed) certificate. A plain
LAN address or
homeassistant.localwon't work even with auth solved; it would need to already be exposed publicly, e.g. via Nabu Casa's remote UI or your own reverse proxy with a real certificate.
Between those two, Claude Desktop generally can't be pointed at this integration directly - use Claude Code instead.
- That flow is built around OAuth - there's no field in it for a static
Bearer token or API key for an individual account. (An org-admin
-
Any other MCP client that supports Streamable HTTP with custom request headers (not just OAuth) can connect the same way as Claude Code: point it at the URL above and set an
Authorization: Bearer <token>header.
Tools
Author & iterate
| Tool | What it does |
|---|---|
find_entities |
Area/domain/name-scoped entity lookup - avoids dumping hundreds of entities |
describe_entity |
Where an entity is defined and which tools read and change it: a UI helper (Template helper of any domain, Min/Max, Utility Meter, ... - the derived-sensor tools), an integration's config entry, an automation or script (with its file), a storage or YAML helper, a YAML template: entity (file and block), a package platform entry, or YAML without a unique_id (with candidates by name) - plus each owning tool's arguments. Start here when diagnosing an entity |
render_template |
Render a Jinja2 template against live state, never raising on error |
validate_template |
Check template syntax and flag referenced entities that don't exist |
get_automation |
Layout-aware read: resolves whether an automation lives in automations.yaml or a packages/*.yaml file, and reports whether it's currently enabled - that's runtime-only state the YAML itself never shows |
write_automation |
Layout-aware, package-safe write - never silently duplicates a package-defined automation, always reloads afterward. The config is checked with HA's own automation validation first: one HA would refuse to set up is refused with HA's error, before any confirm token or write |
delete_automation |
Layout-aware, package-safe delete - resolves which file actually defines it first, refuses to guess if the id isn't found or is defined in more than one file |
list_scripts / get_script / write_script |
Same layout-aware, package-safe pattern as get_automation/write_automation, for script: - resolves whether a script lives in scripts.yaml or a packages/*.yaml file, and writes through the correct one |
list_rest_commands / get_rest_command |
Same layout-aware pattern, for rest_command: - resolves whether it lives in configuration.yaml or a packages/*.yaml file |
write_rest_command / delete_rest_command |
Create, replace or delete a rest_command: entry in a package (configuration.yaml stays read-only). Writes config only; running it still takes an automation or script. Refused: a templated scheme or host, a host no rest_command uses yet unless allow_new_host (the preview says whether it's a LAN or public address), literal credentials (!secret only), and verify_ssl: false unless allow_insecure_tls. The preview shows method, timeout, host and every automation/script calling it |
list_package_platform_entities / write_package_platform_entity / delete_package_platform_entities |
YAML platform entries in packages - sensor: - platform: statistics, binary_sensor:, switch:, ... Found by domain + platform + unique_id (or name), checked against the platform's own schema before writing. command_line is refused (shell execution), rest entries follow the rest_command rules above. The preview shows every reference to the entity; the result says whether a reload took it in or a restart is needed |
check_config |
Home Assistant's own full config validation. With git mirroring on, a passing check also snapshots your hand-edited config (below) and every storage-mode dashboard |
get_config_file |
Raw text of a hand-edited config file - configuration.yaml, anything it !includes, packages/*.yaml, custom_templates/*.jinja - with !secret/!include as written, live or (source: mirror) its last good snapshot. Reads a file that no longer parses, where the structured tools can't. key (e.g. irrigation_unlimited) returns just that top-level block, wherever it lives - an integration's own YAML config. Withholds a file (or with key, a block) with a literal credential in it; never returns secrets.yaml |
reload_domain |
Reload a domain's config (e.g. automation) without restarting; homeassistant reloads the core config (customize, name, units) |
Configure
| Tool | What it does |
|---|---|
list_helpers / create_helper / update_helper / delete_helper |
CRUD for storage-defined helpers (input_boolean, counter, timer, ...), and with domain: area / domain: person / domain: label / domain: category for rooms, persons, labels and the automation/script/scene/helpers pages' categories (a category's id is <scope>/<category_id>) - e.g. link device trackers to a person |
delete_entity |
Soft-delete an entity from the entity registry - Home Assistant reconnects it automatically if the same integration re-registers it later; only truly orphaned entries are purged for good, after 30 days. That 30-day window is Home Assistant's own behavior, not something this tool adds - a backup past it only happens if git mirroring (below) is also turned on |
delete_entities |
Same as delete_entity, for a list of entity_ids in one propose/confirm pair - for bulk cleanup, avoids one round trip (and one mirror commit pair) per entity |
update_entities |
What the entity and device settings dialogs do, for several at once: rename an entity_id, set name, room, device_class, icon, disabled or hidden, and "Show as" a switch as a light/fan/cover/lock/siren/valve, labels (labels sets the whole set, add_labels/remove_labels change it) and categories ({scope: category}); for devices, name, room, disabled and labels. Rooms, labels and categories are matched by exact name or id. Every item is checked first - an unknown room or a taken entity_id refuses the whole batch. A rename onto an id that already has statistics is flagged in the preview, since HA won't move the entity's history onto it. A rename lists every place the old id is used (YAML, dashboards, persons' trackers, helpers); update_references: true rewrites the ones it can |
list_derived_sensors / get_derived_sensor / create_derived_sensor / update_derived_sensor / delete_derived_sensor / reload_derived_sensor |
CRUD for UI-created helpers that are config entries: the Template helper (any entity domain - sensor, binary_sensor, switch, light, ...) and the calculated/derived sensor helpers (Min/Max, Utility Meter, Integration [Riemann sum], Statistics, Threshold, Derivative, Filter) - a second helper family implemented as config entries rather than storage items; create/update discover each step's fields interactively since some of these flows are multi-step or menu-driven (Template's first step picks which entity domain to create); update_derived_sensor also takes a flat options patch of just the fields to change, and leaves every other field as it was |
list_template_entities / get_template_entity / create_template_entity / update_template_entity / delete_template_entity |
Layout-aware, package-safe CRUD for YAML template: entities (sensor, binary_sensor, number, switch, ...) - resolves whether an entity lives in configuration.yaml or a packages/*.yaml file, same pattern as get_automation/write_automation. New entities always go into a package (configuration.yaml itself is read-only here); every write requires the entity to have its own unique_id. update_template_entity can also change a trigger-based block's triggers / conditions / variables / actions in place - the preview lists every entity in the block, and a reload keeps their state (unlike delete + create). For the config-entry Template helper instead, see the row above |
list_dashboards |
List every configured Lovelace dashboard (title, url_path, icon, mode, require_admin, show_in_sidebar) - storage- and YAML-mode alike. Use before get_dashboard when checking every dashboard for something, since a non-default dashboard's url_path otherwise has to already be known |
get_dashboard / write_dashboard |
Read/write a Lovelace dashboard (storage mode; YAML-mode dashboards are read-only here, matching HA's own restriction). get_dashboard also returns the config's config_hash |
patch_dashboard |
Changes part of a dashboard without re-sending the whole config: add/replace/remove a view, section or card, or set a value at a JSON pointer. Everything else is saved exactly as read. Ops are planned against get_dashboard's config_hash (required), and a dashboard changed since is refused. Ambiguous selectors (e.g. two sections with the same heading) are refused. The preview lists each touched node before/after; the result has the new hash for the next patch |
write_customize |
Set or remove homeassistant: customize: attributes in a package for one or more entities - the only way to give an integration's sensor a state_class (needed for long-term statistics) or a missing device_class. Only state_class, device_class, unit_of_measurement, friendly_name, icon and assumed_state, each value checked; combinations HA won't compile statistics for are warned about in the preview. Creates the package file if needed; an entity customized in another file (or configuration.yaml) is refused. Applied without a restart (config check - a new error rolls it back -, reload_core_config, each entity's state rewritten) and reported per entity |
delete_package |
Delete a packages/*.yaml file that holds no configuration any more (only comments, blank lines or {}); one that still holds anything is refused, naming its top-level keys. There's no create_package: every package write tool (write_automation, write_script, create_template_entity, write_package_platform_entity, write_rest_command, write_customize) creates the package file its new content goes into when it doesn't exist yet - a lowercase name (house_state.yaml, heating/rooms.yaml) no other package already has, and only when configuration.yaml loads packages/ with !include_dir_named |
list_esphome_configs / get_esphome_config / write_esphome_config / delete_esphome_config |
The ESPHome Builder's device configs in /config/esphome (subfolders included, for shared !include files) - so an agent compiling on another host can pull the live configs, spot drift from edits made in the add-on, and push changes back. Compiling and flashing stay out of scope. Literal credentials (passwords, api: encryption: key, ...) are masked on read and put back on write; a new literal one is refused - use !secret. secrets.yaml and the .esphome/ build folder are never touched. A write must parse as YAML (ESPHome's own tags allowed), takes expected_hash from the read, and previews as a masked diff; a delete backs the file up first |
get_energy_config / write_energy_config |
Read/write the Energy dashboard's own source config (grid/solar/battery/gas/water entities, cost settings) - a separate HA subsystem from Lovelace dashboards, not reachable through get_dashboard. Each field in a write wholesale-replaces that section; omitting a field leaves it untouched |
Act
| Tool | What it does |
|---|---|
trigger_automation |
Run an existing automation immediately by its config id, the same as the UI's "Run actions" button - for one-shot testing without a throwaway automation edit cycle. Like the button, the run is left to finish on its own - a client timeout never cuts it off; it returns at once with the run's context_id (wait_seconds waits for a short run's outcome). Only ever triggers an automation already in reviewed config; never accepts an arbitrary entity_id or service |
set_automation_enabled |
Turn automations on or off (the UI's enable toggle) by config id, one or several - the preview shows each one's alias, state, last triggered and triggers, so turning one on shows what will start firing. write_automation takes enabled to do the same after a write (a deleted automation restored under its old id otherwise comes back off) |
set_value |
Set the value of an entity that holds one, without an automation: input_text/text (checked against its min/max length and pattern), input_select/select (one of its options), input_number/number (within min/max), counter (a whole number within its bounds), input_datetime (date, time or both, as the helper has), date, time, datetime. The preview shows the current state, the service call and every automation whose triggers name the entity (an enabled one will fire); devices and entities excluded on the Configure page are refused |
set_number_value |
Set a number or input_number entity's value directly (e.g. an EMHASS battery-schedule slot, a Modbus-backed inverter setting) - scoped to exactly these two domains, not a generic service-call tool |
set_boolean_value |
Turn an input_boolean helper on or off directly - scoped to just this virtual helper domain |
control_entities |
Turn entities on, off or toggle them without writing an automation: switch, light (with optional brightness_pct), fan, input_boolean, climate, media_player, humidifier, cover and valve (on opens, off closes). The preview shows each entity's name, area, current state and the service it would call; the result shows each one's state before and after. lock, alarm_control_panel and siren are never controlled, and neither is any device or entity listed under "Devices/Entities agents may never control" on the Configure page (a garage door, say) - such a call is refused before a confirm token is issued |
Diagnose
| Tool | What it does |
|---|---|
get_logs |
Tail/filter/search the core Home Assistant log |
get_entity_history |
Recorder-backed state history for one or more entities over a time range |
get_logbook |
Recorder-backed, humanized logbook entries (automations/scripts triggering, notable state changes) over a time range |
list_traces / get_trace |
Automation and script traces - the automation editor's Traces view. list_traces shows the stored runs (Home Assistant keeps the last 5 per automation/script by default), newest first, with the trigger, how each run ended and any error; get_trace reads one run (the latest by default) step by step: every trigger, condition and action with its result, error and changed variables, and links to the scripts it ran. Accepts an automation's or |
ha-dev-tools MCP questions
What tools does ha-dev-tools MCP provide?
It exposes 34 tools, including find_entities, describe_entity, render_template, validate_template, get_automation.
Can I use this with Claude Desktop?
Claude Desktop generally cannot be pointed at this integration directly because it requires a static Bearer token which the standard connector flow does not support, and it requires a publicly reachable HTTPS URL.
How do I grant the server permission to write to my filesystem?
You must 'arm' the server by running a specific command in your terminal to create an armed file in your configuration storage, which enables write access for a set period.
Is there a way to undo changes made by the AI?
Yes, you can enable optional git mirroring to provide a private before/after history of every change, allowing you to manually restore previous configurations.