@orellbuehler/homeassistant-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Orell Bühler
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,176 @@
+# homeassistant-mcp
+
+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.
+
+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), and
+can reload reloadable domains after YAML edits. It deliberately has **no tools to turn devices on/off,
+set states, or fire events**.
+
+## Install
+
+The package is published as
+[`@orellbuehler/homeassistant-mcp`](https://www.npmjs.com/package/@orellbuehler/homeassistant-mcp)
+and runs directly with `npx` — no clone or build needed:
+
+```bash
+claude mcp add homeassistant \
+  --env HASS_URL=http://homeassistant.local:8123 \
+  --env HASS_TOKEN=your-long-lived-access-token \
+  -- npx -y @orellbuehler/homeassistant-mcp
+```
+
+See [Usage with Claude Code](#usage-with-claude-code) for the equivalent JSON config.
+
+## Getting a token
+
+`HASS_TOKEN` must be a **Long-Lived Access Token**:
+
+1. In Home Assistant, open your profile (click your username, bottom-left).
+2. Go to the **Security** tab → **Long-lived access tokens** → **Create token**.
+3. Copy the token (it is shown only once) and treat it like a password.
+
+The token inherits your user's permissions. To limit what the agent can see, create a dedicated HA
+user with the access you want and generate the token as that user.
+
+## Configuration
+
+| Variable      | Required | Description                                                                       |
+| ------------- | -------- | --------------------------------------------------------------------------------- |
+| `HASS_URL`    | yes\*    | Base URL of your instance, e.g. `http://homeassistant.local:8123`. `https` works. |
+| `HASS_SERVER` | no       | Alias for `HASS_URL` (compatible with `hass-cli`). Used if `HASS_URL` is unset.   |
+| `HASS_TOKEN`  | yes      | Long-lived access token.                                                          |
+
+\* Either `HASS_URL` or `HASS_SERVER` must be set. The WebSocket URL is derived automatically
+(`http`→`ws`, `https`→`wss`, plus `/api/websocket`).
+
+## Usage with Claude Code
+
+Add the server to `~/.claude/settings.json` (or a project `.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "homeassistant": {
+      "command": "npx",
+      "args": ["-y", "@orellbuehler/homeassistant-mcp"],
+      "env": {
+        "HASS_URL": "http://homeassistant.local:8123",
+        "HASS_TOKEN": "your-long-lived-access-token"
+      }
+    }
+  }
+}
+```
+
+If you built from source instead, use `"command": "node"` with
+`"args": ["/path/to/homeassistant-mcp/dist/index.js"]`. Restart Claude Code and the tools are
+available immediately. Verify with `claude mcp list` (should show `homeassistant ✓ connected`) or
+`/mcp` inside a session.
+
+## Tools
+
+**Entities & state** (REST)
+
+| Tool            | Description                                                            |
+| --------------- | ---------------------------------------------------------------------- |
+| `list_entities` | Compact summary of live entities (filter by `domain` and/or `search`). |
+| `get_entity`    | Full state object for one entity, including all attributes.            |
+| `list_domains`  | Distinct entity domains present, with counts.                          |
+
+**Services & events** (REST)
+
+| Tool            | Description                                                                         |
+| --------------- | ----------------------------------------------------------------------------------- |
+| `list_services` | Callable services (actions for automations/scripts). Pass `domain` for full fields. |
+| `list_events`   | Event types being listened for, with listener counts (for `event` triggers).        |
+
+**System & validation** (REST)
+
+| Tool              | Description                                                                    |
+| ----------------- | ------------------------------------------------------------------------------ |
+| `get_config`      | Running config: version, components, unit system, time zone, etc.              |
+| `check_config`    | Validate the YAML config on the server (`/api/config/core/check_config`).      |
+| `get_error_log`   | Error log as text (tail to `lines`, default 100).                              |
+| `render_template` | Render a Jinja2 template against live state — for template sensors/conditions. |
+
+**History** (REST)
+
+| Tool          | Description                                                |
+| ------------- | ---------------------------------------------------------- |
+| `get_history` | State history for one or more entities over a time window. |
+| `get_logbook` | Human-readable logbook entries.                            |
+
+**Reload** (REST, curated allowlist)
+
+| Tool     | Description                                                                                |
+| -------- | ------------------------------------------------------------------------------------------ |
+| `reload` | Reload a reloadable domain so YAML edits apply without a restart (`all`, `automation`, …). |
+
+**Registries** (WebSocket)
+
+| Tool                     | Description                                                                 |
+| ------------------------ | --------------------------------------------------------------------------- |
+| `list_registry_entities` | ALL registered entities, incl. disabled/unavailable (area, device, status). |
+| `list_devices`           | Devices (id, name, manufacturer, model, area).                              |
+| `list_areas`             | Areas (area_id, name, floor).                                               |
+| `list_labels`            | Labels (label_id, name, color, icon).                                       |
+
+`list_entities` (REST) shows entities that currently have state; `list_registry_entities`
+(WebSocket) shows everything registered, including disabled entities, with area/device grouping.
+
+## Safety boundary
+
+- **No device control.** There is no generic `call_service`, no `set_state`, and no `fire_event`.
+  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.
+- **Read tools expose your home's data** (entity names, states, areas) to the agent/LLM. Use a
+  scoped HA user if that matters to you.
+- Prefer `https` and a trusted network path to your instance.
+
+## Development
+
+```bash
+npm install
+npm run build         # tsc -> dist/
+npm test              # vitest run
+npm run typecheck     # tsc --noEmit
+npm run lint          # eslint src
+npm run format:check  # prettier --check .
+```
+
+Run a single test file:
+
+```bash
+npx vitest run src/__tests__/entities.test.ts
+```
+
+## CI / Releasing
+
+- **CI** (`.github/workflows/ci.yml`) runs on every push to `main` and on pull requests:
+  `format:check`, `lint`, `typecheck` (once) and `test` + `build` on Node 20 and 22.
+- **Publish** (`.github/workflows/publish.yml`) runs when a GitHub Release is published. It builds,
+  tests, and publishes to npm using [trusted publishing](https://docs.npmjs.com/trusted-publishers)
+  (OIDC) — **no `NPM_TOKEN` secret required**, with provenance generated automatically. It skips
+  publishing if that version is already on npm.
+
+One-time setup on npmjs.com: open the package's **Settings → Trusted Publisher** and add a GitHub
+Actions publisher for repository `OrellBuehler/homeassistant-mcp` with workflow `publish.yml`. If the
+package doesn't exist on npm yet, do one manual `npm publish --access public` (after `npm login`) to
+create it, then add the trusted publisher for all future releases.
+
+Cut a release:
+
+```bash
+npm version patch          # bumps package.json + creates a vX.Y.Z tag (use minor/major as needed)
+git push --follow-tags
+gh release create "v$(node -p "require('./package.json').version")" --generate-notes
+```
+
+## License
+
+[MIT](./LICENSE) © Orell Bühler

package/dist/config.js

@@ -0,0 +1,26 @@
+import { HassClient } from "./hass/rest.js";
+import { HassWsClient } from "./hass/ws.js";
+const rawUrl = (process.env.HASS_URL || process.env.HASS_SERVER || "").trim();
+const token = (process.env.HASS_TOKEN || "").trim();
+if (!rawUrl || !token) {
+    console.error("HASS_URL (or HASS_SERVER) and HASS_TOKEN environment variables are required. " +
+        "HASS_TOKEN must be a Home Assistant long-lived access token.");
+    process.exit(1);
+}
+function normalizeBaseUrl(url) {
+    const withScheme = /^https?:\/\//i.test(url) ? url : `http://${url}`;
+    return withScheme.replace(/\/+$/, "");
+}
+export function deriveWsUrl(baseUrl) {
+    const ws = baseUrl.replace(/^https:/i, "wss:").replace(/^http:/i, "ws:");
+    return `${ws}/api/websocket`;
+}
+const baseUrl = normalizeBaseUrl(rawUrl);
+export const config = {
+    baseUrl,
+    wsUrl: deriveWsUrl(baseUrl),
+    token,
+    transport: "stdio",
+};
+export const client = new HassClient(baseUrl, token);
+export const wsClient = new HassWsClient(config.wsUrl, token);

package/dist/hass/format.js

@@ -0,0 +1,38 @@
+export function buildQS(params) {
+    const sp = new URLSearchParams();
+    for (const [k, v] of Object.entries(params)) {
+        if (v === undefined || v === null)
+            continue;
+        if (Array.isArray(v)) {
+            if (v.length === 0)
+                continue;
+            sp.set(k, v.join(","));
+        }
+        else {
+            sp.set(k, String(v));
+        }
+    }
+    const s = sp.toString();
+    return s ? `?${s}` : "";
+}
+export function ok(data) {
+    const text = typeof data === "string" ? data : JSON.stringify(data);
+    return { content: [{ type: "text", text }] };
+}
+export function err(e) {
+    return { content: [{ type: "text", text: String(e) }], isError: true };
+}
+export function domainOf(entityId) {
+    return entityId.split(".")[0];
+}
+export function summarizeState(s) {
+    const a = s.attributes ?? {};
+    const out = { entity_id: s.entity_id, state: s.state };
+    if (a.friendly_name !== undefined)
+        out.friendly_name = a.friendly_name;
+    if (a.device_class !== undefined)
+        out.device_class = a.device_class;
+    if (a.unit_of_measurement !== undefined)
+        out.unit = a.unit_of_measurement;
+    return out;
+}

package/dist/hass/rest.js

@@ -0,0 +1,42 @@
+export class HassClient {
+    baseUrl;
+    token;
+    constructor(baseUrl, token) {
+        this.baseUrl = baseUrl.replace(/\/+$/, "");
+        this.token = token;
+    }
+    headers(options) {
+        return {
+            Authorization: `Bearer ${this.token}`,
+            ...(typeof options.body === "string" ? { "Content-Type": "application/json" } : {}),
+            ...(options.headers ?? {}),
+        };
+    }
+    async fetch(path, options = {}) {
+        const res = await fetch(`${this.baseUrl}${path}`, {
+            ...options,
+            headers: this.headers(options),
+        });
+        if (!res.ok) {
+            const body = await res.text();
+            throw new Error(`${res.status} ${res.statusText}: ${body}`);
+        }
+        if (res.status === 204)
+            return { success: true };
+        const ct = res.headers.get("content-type") ?? "";
+        if (ct.includes("application/json"))
+            return res.json();
+        return res.text();
+    }
+    async fetchText(path, options = {}) {
+        const res = await fetch(`${this.baseUrl}${path}`, {
+            ...options,
+            headers: this.headers(options),
+        });
+        if (!res.ok) {
+            const body = await res.text();
+            throw new Error(`${res.status} ${res.statusText}: ${body}`);
+        }
+        return res.text();
+    }
+}

package/dist/hass/ws.js

@@ -0,0 +1,75 @@
+import WebSocket from "ws";
+export class HassWsClient {
+    wsUrl;
+    token;
+    timeoutMs;
+    constructor(wsUrl, token, timeoutMs = 15000) {
+        this.wsUrl = wsUrl;
+        this.token = token;
+        this.timeoutMs = timeoutMs;
+    }
+    command(type, payload = {}) {
+        return new Promise((resolve, reject) => {
+            const ws = new WebSocket(this.wsUrl);
+            const id = 1;
+            let settled = false;
+            const timer = setTimeout(() => {
+                if (settled)
+                    return;
+                settled = true;
+                ws.terminate();
+                reject(new Error(`Home Assistant WebSocket timed out after ${this.timeoutMs}ms`));
+            }, this.timeoutMs);
+            const finish = (run) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                try {
+                    ws.close();
+                }
+                catch {
+                    /* ignore close errors */
+                }
+                run();
+            };
+            ws.on("message", (raw) => {
+                let msg;
+                try {
+                    msg = JSON.parse(raw.toString());
+                }
+                catch (e) {
+                    finish(() => reject(new Error(`Invalid Home Assistant WebSocket message: ${String(e)}`)));
+                    return;
+                }
+                if (msg.type === "auth_required") {
+                    ws.send(JSON.stringify({ type: "auth", access_token: this.token }));
+                }
+                else if (msg.type === "auth_invalid") {
+                    finish(() => reject(new Error(`Home Assistant authentication failed: ${msg.message ?? "invalid token"}`)));
+                }
+                else if (msg.type === "auth_ok") {
+                    ws.send(JSON.stringify({ id, type, ...payload }));
+                }
+                else if (msg.type === "result" && msg.id === id) {
+                    if (msg.success) {
+                        finish(() => resolve(msg.result));
+                    }
+                    else {
+                        finish(() => reject(new Error(`Home Assistant WebSocket error: ${msg.error?.message ?? "unknown error"}`)));
+                    }
+                }
+            });
+            ws.on("error", (e) => {
+                finish(() => reject(new Error(`Home Assistant WebSocket connection error: ${String(e)}`)));
+            });
+            ws.on("close", () => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                reject(new Error("Home Assistant WebSocket closed before a result was received"));
+            });
+        });
+    }
+}

package/dist/index.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { client, wsClient } from "./config.js";
+import { createServer } from "./server.js";
+const server = createServer(client, wsClient);
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/server.js

@@ -0,0 +1,19 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { registerEntityTools } from "./tools/entities.js";
+import { registerServiceTools } from "./tools/services.js";
+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 { registerRegistryTools } from "./tools/registry.js";
+export function createServer(client, wsClient) {
+    const server = new McpServer({ name: "homeassistant-mcp", version: "0.1.0" });
+    registerEntityTools(server, client);
+    registerServiceTools(server, client);
+    registerSystemTools(server, client);
+    registerTemplateTools(server, client);
+    registerHistoryTools(server, client);
+    registerReloadTools(server, client);
+    registerRegistryTools(server, wsClient);
+    return server;
+}

package/dist/tools/entities.js

@@ -0,0 +1,57 @@
+import { z } from "zod";
+import { ok, err, summarizeState, domainOf } from "../hass/format.js";
+export function registerEntityTools(server, client) {
+    server.tool("list_entities", "List entities with their current state as a compact summary (entity_id, state, friendly_name, device_class, unit). Use get_entity for full attributes. Optionally filter by domain and/or a search substring matched against entity_id and friendly_name.", {
+        domain: z
+            .string()
+            .optional()
+            .describe("Only entities in this domain, e.g. 'light', 'sensor', 'binary_sensor'"),
+        search: z
+            .string()
+            .optional()
+            .describe("Case-insensitive substring matched against entity_id and friendly_name"),
+    }, async ({ domain, search }) => {
+        try {
+            const states = (await client.fetch("/api/states"));
+            let rows = states;
+            if (domain)
+                rows = rows.filter((s) => domainOf(s.entity_id) === domain);
+            if (search) {
+                const q = search.toLowerCase();
+                rows = rows.filter((s) => s.entity_id.toLowerCase().includes(q) ||
+                    String(s.attributes?.friendly_name ?? "")
+                        .toLowerCase()
+                        .includes(q));
+            }
+            return ok({ count: rows.length, entities: rows.map(summarizeState) });
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
+    server.tool("get_entity", "Get the full state object for a single entity, including all attributes, last_changed and last_updated.", { entity_id: z.string().describe("Entity ID, e.g. 'light.kitchen'") }, async ({ entity_id }) => {
+        try {
+            return ok(await client.fetch(`/api/states/${encodeURIComponent(entity_id)}`));
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
+    server.tool("list_domains", "List the distinct entity domains present on this instance with a count of entities in each. Useful for discovering what kinds of entities exist before drilling in with list_entities.", {}, async () => {
+        try {
+            const states = (await client.fetch("/api/states"));
+            const counts = new Map();
+            for (const s of states) {
+                const d = domainOf(s.entity_id);
+                counts.set(d, (counts.get(d) ?? 0) + 1);
+            }
+            const domains = [...counts.entries()]
+                .map(([domain, count]) => ({ domain, count }))
+                .sort((a, b) => a.domain.localeCompare(b.domain));
+            return ok({ count: domains.length, domains });
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
+}

package/dist/tools/history.js

@@ -0,0 +1,57 @@
+import { z } from "zod";
+import { buildQS, ok, err } from "../hass/format.js";
+export function registerHistoryTools(server, client) {
+    server.tool("get_history", "Get state history for one or more entities (GET /api/history/period). Returns arrays of past state changes — useful for understanding how an entity behaves before writing triggers and conditions.", {
+        entity_id: z
+            .string()
+            .describe("Entity ID, or a comma-separated list of entity IDs, to fetch history for"),
+        start: z
+            .string()
+            .optional()
+            .describe("ISO 8601 start timestamp, e.g. '2026-06-01T00:00:00'. Defaults to 1 day ago on the HA side."),
+        end: z.string().optional().describe("ISO 8601 end timestamp"),
+        minimal_response: z
+            .boolean()
+            .optional()
+            .describe("Return only last_changed and state for most entries (smaller payload)"),
+        significant_changes_only: z
+            .boolean()
+            .optional()
+            .describe("Only return significant state changes"),
+        no_attributes: z.boolean().optional().describe("Omit attributes from the response"),
+    }, async ({ entity_id, start, end, minimal_response, significant_changes_only, no_attributes, }) => {
+        try {
+            const base = start
+                ? `/api/history/period/${encodeURIComponent(start)}`
+                : "/api/history/period";
+            const qs = buildQS({
+                filter_entity_id: entity_id,
+                end_time: end,
+                minimal_response: minimal_response ? true : undefined,
+                significant_changes_only: significant_changes_only ? true : undefined,
+                no_attributes: no_attributes ? true : undefined,
+            });
+            return ok(await client.fetch(`${base}${qs}`));
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
+    server.tool("get_logbook", "Get logbook entries — human-readable events such as state changes and automation triggers (GET /api/logbook). Useful for seeing what happened and when.", {
+        entity_id: z.string().optional().describe("Limit to a single entity"),
+        start: z
+            .string()
+            .optional()
+            .describe("ISO 8601 start timestamp. Defaults to 1 day ago on the HA side."),
+        end: z.string().optional().describe("ISO 8601 end timestamp"),
+    }, async ({ entity_id, start, end }) => {
+        try {
+            const base = start ? `/api/logbook/${encodeURIComponent(start)}` : "/api/logbook";
+            const qs = buildQS({ entity: entity_id, end_time: end });
+            return ok(await client.fetch(`${base}${qs}`));
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
+}

package/dist/tools/registry.js

@@ -0,0 +1,66 @@
+import { z } from "zod";
+import { ok, err, domainOf } from "../hass/format.js";
+export function registerRegistryTools(server, ws) {
+    server.tool("list_registry_entities", "List ALL registered entities from the entity registry via the WebSocket API — including disabled and currently-unavailable entities that GET /api/states (list_entities) omits. Includes name, platform, area_id, device_id, entity_category and disabled_by. Optionally filter by domain.", {
+        domain: z
+            .string()
+            .optional()
+            .describe("Only entities in this domain, e.g. 'light', 'sensor'"),
+        include_disabled: z.boolean().optional().describe("Include disabled entities (default true)"),
+    }, async ({ domain, include_disabled }) => {
+        try {
+            const list = (await ws.command("config/entity_registry/list"));
+            let rows = list;
+            if (domain)
+                rows = rows.filter((e) => domainOf(e.entity_id) === domain);
+            if (include_disabled === false)
+                rows = rows.filter((e) => !e.disabled_by);
+            const entities = rows.map((e) => ({
+                entity_id: e.entity_id,
+                name: e.name ?? e.original_name ?? null,
+                platform: e.platform ?? null,
+                area_id: e.area_id ?? null,
+                device_id: e.device_id ?? null,
+                entity_category: e.entity_category ?? null,
+                disabled_by: e.disabled_by ?? null,
+                hidden_by: e.hidden_by ?? null,
+            }));
+            return ok({ count: entities.length, entities });
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
+    server.tool("list_devices", "List devices from the device registry via the WebSocket API (id, name, manufacturer, model, area_id). Useful for grouping entities by physical device when writing automations.", {}, async () => {
+        try {
+            const list = (await ws.command("config/device_registry/list"));
+            const devices = list.map((d) => ({
+                id: d.id,
+                name: d.name_by_user ?? d.name ?? null,
+                manufacturer: d.manufacturer ?? null,
+                model: d.model ?? null,
+                area_id: d.area_id ?? null,
+            }));
+            return ok({ count: devices.length, devices });
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
+    server.tool("list_areas", "List areas from the area registry via the WebSocket API (area_id, name, floor_id, icon). Areas group devices and entities by room or location.", {}, async () => {
+        try {
+            return ok(await ws.command("config/area_registry/list"));
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
+    server.tool("list_labels", "List labels from the label registry via the WebSocket API (label_id, name, color, icon). Labels are cross-cutting tags applied to entities, devices and areas.", {}, async () => {
+        try {
+            return ok(await ws.command("config/label_registry/list"));
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
+}

package/dist/tools/reload.js

@@ -0,0 +1,40 @@
+import { z } from "zod";
+import { ok, err } from "../hass/format.js";
+const RELOAD_TARGETS = {
+    all: { domain: "homeassistant", service: "reload_all" },
+    core: { domain: "homeassistant", service: "reload_core_config" },
+    automation: { domain: "automation", service: "reload" },
+    script: { domain: "script", service: "reload" },
+    scene: { domain: "scene", service: "reload" },
+    template: { domain: "template", service: "reload" },
+    group: { domain: "group", service: "reload" },
+    zone: { domain: "zone", service: "reload" },
+    person: { domain: "person", service: "reload" },
+    timer: { domain: "timer", service: "reload" },
+    schedule: { domain: "schedule", service: "reload" },
+    counter: { domain: "counter", service: "reload" },
+    input_boolean: { domain: "input_boolean", service: "reload" },
+    input_number: { domain: "input_number", service: "reload" },
+    input_select: { domain: "input_select", service: "reload" },
+    input_text: { domain: "input_text", service: "reload" },
+    input_datetime: { domain: "input_datetime", service: "reload" },
+    input_button: { domain: "input_button", service: "reload" },
+    rest_command: { domain: "rest_command", service: "reload" },
+    command_line: { domain: "command_line", service: "reload" },
+    mqtt: { domain: "mqtt", service: "reload" },
+};
+const targets = Object.keys(RELOAD_TARGETS);
+export function registerReloadTools(server, client) {
+    server.tool("reload", "Reload a reloadable Home Assistant domain so YAML edits take effect without a full restart. Restricted to a fixed allowlist of safe reload services — it cannot control devices. Use 'all' (homeassistant.reload_all) to reload everything reloadable, or 'core' (homeassistant.reload_core_config) for core config like customize. Run check_config first.", {
+        target: z.enum(targets).describe(`What to reload. One of: ${targets.join(", ")}`),
+    }, async ({ target }) => {
+        try {
+            const { domain, service } = RELOAD_TARGETS[target];
+            const result = await client.fetch(`/api/services/${domain}/${service}`, { method: "POST" });
+            return ok({ reloaded: target, service: `${domain}.${service}`, result });
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
+}

package/dist/tools/services.js

@@ -0,0 +1,33 @@
+import { z } from "zod";
+import { ok, err } from "../hass/format.js";
+export function registerServiceTools(server, client) {
+    server.tool("list_services", "List services that can be called — the actions available in automations and scripts. With no domain, returns a compact map of domain -> service names. Pass a domain to get full detail (description, fields, target, selectors) for that domain's services.", {
+        domain: z
+            .string()
+            .optional()
+            .describe("Only this domain, e.g. 'light', 'notify', 'automation'. Returns full field/target detail when set."),
+    }, async ({ domain }) => {
+        try {
+            const data = (await client.fetch("/api/services"));
+            if (domain) {
+                const entry = data.find((d) => d.domain === domain);
+                return ok(entry ?? { domain, services: {} });
+            }
+            const domains = data
+                .map((d) => ({ domain: d.domain, services: Object.keys(d.services ?? {}) }))
+                .sort((a, b) => a.domain.localeCompare(b.domain));
+            return ok({ count: domains.length, domains });
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
+    server.tool("list_events", "List the event types the instance is currently listening for, with listener counts. Useful for discovering events to use as automation triggers (the 'event' trigger platform).", {}, async () => {
+        try {
+            return ok(await client.fetch("/api/events"));
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
+}

package/dist/tools/system.js

@@ -0,0 +1,39 @@
+import { z } from "zod";
+import { ok, err } from "../hass/format.js";
+export function registerSystemTools(server, client) {
+    server.tool("get_config", "Get the running Home Assistant configuration: version, location, unit system, time zone, currency, config directory, and the list of loaded components/integrations. Also serves as a connectivity/token check.", {}, async () => {
+        try {
+            return ok(await client.fetch("/api/config"));
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
+    server.tool("check_config", "Validate the Home Assistant YAML configuration currently on the server (POST /api/config/core/check_config). Returns { result: 'valid' | 'invalid', errors }. Requires the 'config' integration (included in default_config). Run this after editing YAML and before reloading or restarting.", {}, async () => {
+        try {
+            return ok(await client.fetch("/api/config/core/check_config", { method: "POST" }));
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
+    server.tool("get_error_log", "Get the Home Assistant error log as plain text. Returns the most recent lines (default 100). Useful for diagnosing why a config or automation failed to load.", {
+        lines: z
+            .number()
+            .int()
+            .optional()
+            .describe("Number of trailing lines to return (default 100; use 0 for the full log)"),
+    }, async ({ lines }) => {
+        try {
+            const text = await client.fetchText("/api/error_log");
+            const n = lines ?? 100;
+            if (n > 0) {
+                return ok(text.split("\n").slice(-n).join("\n"));
+            }
+            return ok(text);
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
+}

package/dist/tools/templates.js

@@ -0,0 +1,21 @@
+import { z } from "zod";
+import { ok, err } from "../hass/format.js";
+export function registerTemplateTools(server, client) {
+    server.tool("render_template", "Render a Home Assistant Jinja2 template against live state and return the result as text (POST /api/template). Use this to develop and debug template sensors, template conditions, and automation templates, e.g. \"{{ states('sensor.temperature') | float > 20 }}\". Read-only: HA renders without side effects.", {
+        template: z
+            .string()
+            .describe("Jinja2 template string, e.g. \"{{ states('sensor.temperature') }}\""),
+        variables: z
+            .record(z.unknown())
+            .optional()
+            .describe("Optional variables made available to the template"),
+    }, async ({ template, variables }) => {
+        try {
+            const body = JSON.stringify(variables ? { template, variables } : { template });
+            return ok(await client.fetchText("/api/template", { method: "POST", body }));
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
+}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@orellbuehler/homeassistant-mcp",
+  "version": "0.1.0",
+  "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": {
+    "homeassistant-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "!dist/__tests__"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "prepare": "npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "home-assistant",
+    "homeassistant",
+    "hass",
+    "home-automation",
+    "llm",
+    "ai"
+  ],
+  "author": "Orell Bühler",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OrellBuehler/homeassistant-mcp.git"
+  },
+  "homepage": "https://github.com/OrellBuehler/homeassistant-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/OrellBuehler/homeassistant-mcp/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "ws": "^8.18.0",
+    "zod": "^3.24.4"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^22.15.3",
+    "@types/ws": "^8.5.12",
+    "eslint": "^10.4.1",
+    "eslint-config-prettier": "^10.1.8",
+    "prettier": "^3.8.3",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.60.0",
+    "vitest": "^4.1.0"
+  }
+}