@orellbuehler/homeassistant-mcp 0.6.0 → 0.7.1

package/README.md

@@ -1,20 +1,46 @@
-# homeassistant-mcp
+# Home Assistant MCP Server
 
 [![npm](https://img.shields.io/npm/v/@orellbuehler/homeassistant-mcp.svg)](https://www.npmjs.com/package/@orellbuehler/homeassistant-mcp)
+[![npm downloads](https://img.shields.io/npm/dm/@orellbuehler/homeassistant-mcp.svg)](https://www.npmjs.com/package/@orellbuehler/homeassistant-mcp)
 [![CI](https://github.com/OrellBuehler/homeassistant-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/OrellBuehler/homeassistant-mcp/actions/workflows/ci.yml)
 [![node](https://img.shields.io/node/v/@orellbuehler/homeassistant-mcp.svg)](https://nodejs.org)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 
-MCP server for [Home Assistant](https://www.home-assistant.io/) that exposes the
-[REST API](https://www.home-assistant.io/integrations/api/) and WebSocket registries as tools for
-AI agents.
+A [Model Context Protocol](https://modelcontextprotocol.io/) server that turns your
+[Home Assistant](https://www.home-assistant.io/) instance into a safe workbench for AI agents —
+built to **author and validate configuration and automations**, not to control your home.
 
-It is built to **help an agent author and validate Home Assistant configuration and automations** —
-not to control your home. It tells the agent what exists live (entities, services, events, areas,
-devices), validates the agent's work (render Jinja2 templates, check config, read the error log),
-can reload reloadable domains after YAML edits, can configure the Energy dashboard (sources and the
-Individual-devices list), manage Lovelace resources, and prune HACS repositories. It deliberately has
-**no tools to turn devices on/off, set states, or fire events**.
+Point Claude (or any MCP client) at it and the agent can:
+
+- **See what exists, live** — entities, services, events, areas, devices, labels, state history,
+  logbook.
+- **Author configuration** — create/edit automations, configure the Energy dashboard, manage
+  Zigbee (ZHA) groups, register Lovelace resources, prune HACS repositories, rename entities,
+  reload YAML domains.
+- **Validate its own work** — render Jinja2 templates against live state, run HA's config check,
+  read the error log, and inspect step-by-step execution traces of automations it wrote.
+- **Never touch your devices** — there is deliberately no `call_service`, no `set_state`, and no
+  `fire_event`. The agent writes config; it cannot turn anything on or off.
+
+42 tools, zero install (`npx`), works with Claude Code, Claude Desktop, Cursor, and any other MCP
+client.
+
+## Example prompts
+
+> "Create an automation that turns on the porch light 30 minutes before sunset, but only when
+> someone is home."
+
+> "My 'goodnight' automation didn't fire last night. Figure out why."
+
+> "Write a template sensor for net grid power and validate it against live state before I put it
+> in my YAML."
+
+> "Set up my Energy dashboard: grid import/export from these two sensors, solar from the inverter,
+> and add every smart plug as an individual device."
+
+> "Group the three living-room bulbs into one Zigbee group so they dim in sync."
+
+> "I uninstalled a HACS card — find and remove the dangling Lovelace resource."
 
 ## Install
 
@@ -81,6 +107,10 @@ available immediately. Verify with `claude mcp list` (should show `homeassistant
 
 ## Tools
 
+42 tools in 12 groups. REST tools go through the
+[Home Assistant REST API](https://www.home-assistant.io/integrations/api/); WebSocket tools use the
+config registries that are not exposed over REST.
+
 **Entities & state** (REST)
 
 | Tool            | Description                                                            |
@@ -118,6 +148,21 @@ available immediately. Verify with `claude mcp list` (should show `homeassistant
 | -------- | ------------------------------------------------------------------------------------------ |
 | `reload` | Reload a reloadable domain so YAML edits apply without a restart (`all`, `automation`, …). |
 
+**Automations** (REST, `/api/config/automation`)
+
+| Tool                    | Description                                                                    |
+| ----------------------- | ------------------------------------------------------------------------------ |
+| `get_automation_config` | Stored config (triggers/conditions/actions/mode) of one automation.            |
+| `upsert_automation`     | Create a new automation or replace an existing one's config (validated by HA). |
+| `delete_automation`     | Delete a UI-managed automation.                                                |
+
+All three accept the `automation.*` entity id (the internal id is resolved automatically) or the
+internal id itself. Writes require an **admin token**; HA validates the config, stores it in
+`automations.yaml` and reloads automations automatically. `upsert_automation` replaces the whole
+config, so edit via `get_automation_config` → modify → `upsert_automation`. Only automations with
+an `id` (UI-created / `automations.yaml`) are reachable — automations defined elsewhere in YAML are
+not. Debug the result with the trace tools below.
+
 **Registries** (WebSocket)
 
 | Tool                     | Description                                                                              |
@@ -206,8 +251,9 @@ is globally in YAML mode. This is config authoring, not device control.
 
 `list_hacs_repositories` maps each repo to `id` + `local_path`/`file_name`, so you can tell which
 `/hacsfiles/…` Lovelace resource belongs to a plugin. `remove_hacs_repository` calls
-`hacs/repository/remove` (**admin token**) and deletes the plugin's files, but not its Lovelace
-resource — pair it with `delete_lovelace_resource` to fully clean up a frontend plugin. Removing an
+`hacs/repository/remove` (**admin token**) and deletes the plugin's files; when HACS manages
+resources (storage mode) it also drops the plugin's Lovelace resource for you, so verify with
+`list_lovelace_resources` and only `delete_lovelace_resource` one that's left behind. Removing an
 integration you still reference in YAML will break that config, so check usage first.
 
 ## Safety boundary
@@ -216,6 +262,11 @@ integration you still reference in YAML will break that config, so check usage f
   The server cannot turn things on/off.
 - **`reload` is restricted** to a fixed allowlist of `*.reload` / `homeassistant.reload_*` services.
   It restarts reloadable domains (e.g. re-reads `automations.yaml`) but cannot control devices.
+- **Automation configs are writable** via the `/api/config/automation` REST API
+  (`upsert_automation` / `delete_automation`). This is the server's core purpose — authoring
+  automations — and needs an admin token. Be aware that an automation, once written, runs its
+  actions whenever its triggers fire, so review configs before writing. The server still cannot run
+  services directly: no `call_service`, `set_state`, or `fire_event`.
 - **Energy dashboard config is writable** via `energy/save_prefs` (the `*_energy_*` tools). This is
   configuration authoring — the dashboard's sources and Individual-devices list — not device control,
   and it needs an admin token. No `call_service`, `set_state`, or `fire_event` is added.

package/dist/server.js

@@ -5,6 +5,7 @@ import { registerSystemTools } from "./tools/system.js";
 import { registerTemplateTools } from "./tools/templates.js";
 import { registerHistoryTools } from "./tools/history.js";
 import { registerReloadTools } from "./tools/reload.js";
+import { registerAutomationTools } from "./tools/automations.js";
 import { registerRegistryTools } from "./tools/registry.js";
 import { registerEnergyTools } from "./tools/energy.js";
 import { registerTraceTools } from "./tools/trace.js";
@@ -12,13 +13,14 @@ import { registerZhaTools } from "./tools/zha.js";
 import { registerHacsTools } from "./tools/hacs.js";
 import { registerResourceTools } from "./tools/resources.js";
 export function createServer(client, wsClient) {
-    const server = new McpServer({ name: "homeassistant-mcp", version: "0.6.0" });
+    const server = new McpServer({ name: "homeassistant-mcp", version: "0.7.0" });
     registerEntityTools(server, client);
     registerServiceTools(server, client);
     registerSystemTools(server, client);
     registerTemplateTools(server, client);
     registerHistoryTools(server, client);
     registerReloadTools(server, client);
+    registerAutomationTools(server, client);
     registerRegistryTools(server, wsClient);
     registerEnergyTools(server, wsClient, client);
     registerTraceTools(server, wsClient, client);

package/dist/tools/automations.js

@@ -0,0 +1,62 @@
+import { z } from "zod";
+import { ok, err } from "../hass/format.js";
+async function resolveId(automation, client) {
+    if (!automation.startsWith("automation."))
+        return automation;
+    const state = (await client.fetch(`/api/states/${encodeURIComponent(automation)}`));
+    const id = state.attributes?.id;
+    if (id === undefined || id === null || id === "") {
+        throw new Error(`Automation ${automation} has no 'id' attribute, so it is not stored in automations.yaml and cannot be read or edited via the config API (it is defined elsewhere in YAML without an id)`);
+    }
+    return String(id);
+}
+const configPath = (id) => `/api/config/automation/config/${encodeURIComponent(id)}`;
+export function registerAutomationTools(server, client) {
+    server.tool("get_automation_config", "Get the stored configuration of an automation (alias, description, triggers, conditions, actions, mode) from automations.yaml via GET /api/config/automation/config/{id}. Accepts the automation.* entity id (the internal id is resolved automatically) or the internal id itself. Only automations with an 'id' (UI-created, stored in automations.yaml) are accessible.", {
+        automation: z
+            .string()
+            .describe("automation.* entity id, or the automation's internal id (the 'id' attribute)"),
+    }, async ({ automation }) => {
+        try {
+            const id = await resolveId(automation, client);
+            return ok(await client.fetch(configPath(id)));
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
+    server.tool("upsert_automation", "Create a new automation or replace an existing one via POST /api/config/automation/config/{id} (requires an admin token). Home Assistant validates the config, writes it to automations.yaml and reloads automations automatically — no separate reload needed. The config REPLACES the stored one entirely, so to edit call get_automation_config first and send back the modified object. Omit 'automation' to create a new one (an id is generated and returned); its entity id becomes automation.<slugified alias>. Note that once its triggers fire, an automation runs its actions — review the config before writing.", {
+        config: z
+            .record(z.unknown())
+            .describe("Full automation config as stored in automations.yaml: alias, description?, triggers, conditions?, actions, mode? (the legacy singular trigger/condition/action keys are also accepted)"),
+        automation: z
+            .string()
+            .optional()
+            .describe("Existing automation.* entity id or internal id to replace; omit to create a new automation"),
+    }, async ({ config, automation }) => {
+        try {
+            const id = automation ? await resolveId(automation, client) : String(Date.now());
+            const result = await client.fetch(configPath(id), {
+                method: "POST",
+                body: JSON.stringify(config),
+            });
+            return ok({ id, created: !automation, result });
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
+    server.tool("delete_automation", "Delete an automation from automations.yaml via DELETE /api/config/automation/config/{id} (requires an admin token). Accepts the automation.* entity id or the internal id. Only UI-managed automations (those stored in automations.yaml) can be deleted; Home Assistant reloads automations automatically afterwards.", {
+        automation: z
+            .string()
+            .describe("automation.* entity id, or the automation's internal id (the 'id' attribute)"),
+    }, async ({ automation }) => {
+        try {
+            const id = await resolveId(automation, client);
+            return ok(await client.fetch(configPath(id), { method: "DELETE" }));
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
+}

package/dist/tools/hacs.js

@@ -36,7 +36,7 @@ export function registerHacsTools(server, ws) {
             return err(e);
         }
     });
-    server.tool("remove_hacs_repository", "Uninstall a HACS repository by id (hacs/repository/remove) — deletes its downloaded files from the config (for a plugin, the JS under www/community/…) and unregisters it from HACS. Requires an admin token. This does NOT remove the plugin's Lovelace resource entry; after removing a frontend plugin, also delete its /hacsfiles/… resource with delete_lovelace_resource. Get the id from list_hacs_repositories. Removing an installed integration you still reference in YAML will break that config, so confirm nothing uses it first.", {
+    server.tool("remove_hacs_repository", "Uninstall a HACS repository by id (hacs/repository/remove) — deletes its downloaded files from the config (for a plugin, the JS under www/community/…) and unregisters it from HACS. Requires an admin token. When HACS manages resources (storage mode) it also removes the plugin's /hacsfiles/… Lovelace resource for you; verify with list_lovelace_resources and use delete_lovelace_resource only if one is left behind. Get the id from list_hacs_repositories. Removing an installed integration you still reference in YAML will break that config, so confirm nothing uses it first.", {
         repository_id: z
             .string()
             .describe("The repository id from list_hacs_repositories (a numeric string, e.g. '172733314')."),

package/dist/tools/resources.js

@@ -42,7 +42,7 @@ export function registerResourceTools(server, ws) {
             return err(e);
         }
     });
-    server.tool("delete_lovelace_resource", "Delete a Lovelace resource (lovelace/resources/delete) by id — removes the JS/CSS URL from every dashboard. Config authoring; requires an admin token and storage-mode resources. Use this to clear the dangling /hacsfiles/… resource left behind after remove_hacs_repository. Get the resource_id from list_lovelace_resources.", {
+    server.tool("delete_lovelace_resource", "Delete a Lovelace resource (lovelace/resources/delete) by id — removes the JS/CSS URL from every dashboard. Config authoring; requires an admin token and storage-mode resources. Use this for manually-registered resources (e.g. /local/…) or a /hacsfiles/… resource that HACS did not auto-remove after remove_hacs_repository. Get the resource_id from list_lovelace_resources.", {
         resource_id: z.string().describe("The resource id from list_lovelace_resources."),
     }, async ({ resource_id }) => {
         try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orellbuehler/homeassistant-mcp",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "Model Context Protocol server for Home Assistant: introspect entities, services, events, registries, render templates and validate configuration to help AI agents author HA configs and automations.",
   "type": "module",
   "bin": {
@@ -26,11 +26,16 @@
   },
   "keywords": [
     "mcp",
+    "mcp-server",
     "model-context-protocol",
     "home-assistant",
     "homeassistant",
     "hass",
     "home-automation",
+    "smart-home",
+    "automation",
+    "claude",
+    "ai-agents",
     "llm",
     "ai"
   ],