home-assistant-mcp

A Model Context Protocol server for Home Assistant over its REST API, in ~250 lines of TypeScript with one dependency.

Two layers:

1. Generic tools — read states, call any service. Enough for an agent to operate a home it has never seen.

2. A scene catalog (optional) — a JSON file of named presets with plain-English descriptions that the agent can list and apply by name. "Make it cinema" becomes ha_scene {"name":"cinema"} instead of the model guessing 18 bulb entity ids and color temperatures. Presets are just script.* or scene.* entities you already have.

Tools

Related MCP server: Home Assistant MCP Server

Setup

npm install
npm run build          # tsc -> dist/server.js
HA_URL=http://homeassistant.local:8123 HA_TOKEN=... node dist/server.js

MCP client registration (stdio):

{
  "mcpServers": {
    "home-assistant": {
      "command": "node",
      "args": ["/path/to/home-assistant-mcp/dist/server.js"],
      "env": {
        "HA_URL": "http://homeassistant.local:8123",
        "HA_TOKEN": "<token>",
        "HA_SCENES_FILE": "/path/to/scenes.json"
      }
    }
  }
}

Scene catalog pattern

The example catalog is the 13-theme setup this was written for. Each preset is layered in Home Assistant so the same name works from any surface:

scene.home_<name>    canonical light state (scenes.yaml)
script.home_<name>   thin wrapper -> scene.turn_on, plus any extras (scripts.yaml)
ha_scene <name>      MCP -> script.turn_on via REST

Anything else (n8n, a dashboard button, a voice assistant) can call the same script, so the agent and the humans share one vocabulary. Keep the descriptions honest — they are what the model reads to choose.

Notes

• HA_TOKEN is a secret; pass it via environment, never commit it.

• Use on a trusted network or via a VPN; this server does not add authentication of its own.

License

MIT — see LICENSE.