reyhanfahlevi/homeassistant-mcp

0 stars 0 forks Quality 78 Trend 20MIT

MCP server for the Home Assistant REST API: states, services, history, templates, events. Long-lived access token.

Overview

MCP server for the Home Assistant REST API, authenticated with a long-lived access token. 1. In Home Assistant: open your profile (http:// :8123/profile) → → . Copy the whole string. 2. Add the server to your MCP client: HA_URL / HA_TOKEN are accepted as aliases. Use http:// and the port the instance runs on (8123 unless changed; 80 on Home Assistant OS). No trailing slash needed. Not on npm yet — clone, build, and point the client at the folder: node /absolute/path/to/homeassistant-mcp/dist/index.js works too. Endpoints not covered directly (/api/components, /api/events, /api/config/core/check_config, …) go through ha_call_api, e.g. {"method": "GET", "path": "/api/components"}. Not covered by the REST API at all: the device/area/entity and long-term statistics. Those only exist over the WebSocket API — a separate server would be needed.

README

@reyhanfahlevi/homeassistant-mcp

MCP server for the Home Assistant REST API, authenticated with a long-lived access token.

Setup

In Home Assistant: open your profile (http://:8123/profile) → Long-Lived Access Tokens → Create Token. Copy the whole string.
Add the server to your MCP client:

{
  "mcpServers": {
    "homeassistant": {
      "command": "npx",
      "args": ["-y", "@reyhanfahlevi/homeassistant-mcp"],
      "env": {
        "HOMEASSISTANT_URL": "http://homeassistant.local:8123",
        "HOMEASSISTANT_TOKEN": "eyJhbGciOiJIUzI1NiIs..."
      }
    }
  }
}

HA_URL / HA_TOKEN are accepted as aliases. Use http:// and the port the instance runs on (8123 unless changed; 80 on Home Assistant OS). No trailing slash needed.

From a local checkout

Not on npm yet — clone, build, and point the client at the folder:

git clone https://github.com/reyhanfahlevi/homeassistant-mcp && cd homeassistant-mcp
npm install && npm run build

"command": "npx",
"args": ["-y", "/absolute/path/to/homeassistant-mcp"]

node /absolute/path/to/homeassistant-mcp/dist/index.js works too.

Tools

Tool	Type	Purpose
`ha_get_config`	read	Instance config: location, units, version, components
`ha_list_states`	read	Entity states, filtered by `domain` and paged
`ha_get_state`	read	One entity’s state and attributes
`ha_list_services`	read	Callable services; with `domain`, their fields
`ha_get_history`	read	State history of entities over a period
`ha_get_logbook`	read	Human-readable activity entries
`ha_get_error_log`	read	Errors from the current session
`ha_render_template`	read	Render a Jinja2 template server-side
`ha_list_calendars`	read	Calendar entities
`ha_get_calendar_events`	read	Events in a calendar between timestamps
`ha_call_service`	write	Control devices, e.g. `light` / `turn_on`
`ha_fire_event`	write	Fire an event on the event bus
`ha_set_state`	write	Overwrite an entity’s state (representation only, no device I/O)
`ha_delete_state`	destructive	Remove a manually created entity
`ha_call_api`	any	Any other path under `/api`

Endpoints not covered directly (/api/components, /api/events, /api/config/core/check_config, …) go through ha_call_api, e.g. {"method": "GET", "path": "/api/components"}.

Not covered by the REST API at all: the device/area/entity registries and long-term statistics. Those only exist over the WebSocket API — a separate server would be needed.

Development

npm install
npm run build              # tsc -> dist/
npm test                   # unit checks on the path/format helpers
npm run smoke              # boots dist/ over stdio and lists tools (+ live calls if env is set)
HOMEASSISTANT_URL=http://homeassistant.local:8123 HOMEASSISTANT_TOKEN=... npm run smoke

License

MIT

View this README on GitHub

Install

npx -y @reyhanfahlevi/homeassistant-mcp

Configuration

{
  "mcpServers": {
    "homeassistant": {
      "command": "npx",
      "args": ["-y", "@reyhanfahlevi/homeassistant-mcp"],
      "env": {
        "HOMEASSISTANT_URL": "http://homeassistant.local:8123",
        "HOMEASSISTANT_TOKEN": "eyJhbGciOiJIUzI1NiIs..."
      }
    }
  }
}