<img src="https://raw.githubusercontent.com/alexlenk/ha-dev-tools/main/custom_components/ha_dev_tools/brand/icon.png" width="72" align="left" alt="HA Dev Tools MCP logo">

HA Dev 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.8.2+ (see Requirements below for the full list, including client-specific versions).

1. Install via HACS or manually - see Installation below.

2. Settings → Devices & Services → Add Integration → HA Dev Tools.

3. Settings → Devices & Services → Add Integration → Model Context Protocol Server (Home Assistant's own built-in integration) - in its setup, add dev_tools to the exposed APIs. This step is easy to miss and is the single most common way to end up stuck: skip it and HA Dev Tools' card still shows healthy, but an MCP client just gets a bare 404 (a Settings → System → Repairs issue will flag it if you do).

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

   This enables dev_tools for up to 4 hours (extended by 30 minutes each time a tool is used, and it expires on its own after 30 minutes idle). 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
   

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

   See 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) 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.8.2 or newer - the release that shipped the native mcp_server integration this depends on. That release itself requires Python 3.14.2+.
• The mcp_server integration, configured to expose the dev_tools API (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. Run claude update if unsure.

Installation

HACS (recommended)

1. Open HACS and search for HA Dev Tools MCP (it's in the default HACS list, so no custom repository is needed).
2. Download it.
3. Restart Home Assistant.

Manual

1. Download the latest release.
2. Copy the ha_dev_tools folder into <config>/custom_components/.
3. 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 list afterward 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_headers connector option exists on some plans and can carry a fixed Authorization header 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.local won'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.

• 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 | | 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 too