Skip to main content
Glama

ha-mcp

A self-hosted Model Context Protocol server for Home Assistant, in TypeScript. It gives an MCP client (Claude Desktop, Claude Code, Codex CLI, …) the full Home Assistant control surface: read any entity's state, call any service, query history, render templates, and resolve rooms/areas - over a single local stdio connection.

Why

Home Assistant ships an official MCP Server integration, but it's deliberately narrow: it only exposes the Assist intent layer over entities you've explicitly exposed to voice assistants - no raw states, no arbitrary service calls, no history, no templates, no area registry. ha-mcp wraps the documented REST and WebSocket APIs directly, so the model can work with everything in your instance.

Related MCP server: HA Vibecode Agent

Tools

Tool

What it does

ha_get_states

List entity states; optional domain and/or area filter

ha_get_entity

Full state + attributes for one entity_id

ha_call_service

Call any service (light.turn_on, climate.set_temperature, automation.trigger, scene.turn_on, …)

ha_get_history

State-change history for an entity over the last N hours

ha_render_template

Render a Jinja2 template against live state

ha_get_config

HA version, location, unit system, components

ha_get_error_log

The error log, for troubleshooting

ha_list_areas

All areas/rooms

ha_get_entities_by_area

Entities in a room, resolving device→area inheritance

Listing automations is just ha_get_states filtered to automation.*; triggering one is ha_call_service('automation','trigger'). Scenes and scripts work the same way - no separate tools needed.

Requirements

  • Node.js ≥ 20

  • A Home Assistant instance and a long-lived access token (HA → your profile → Security → Long-lived access tokens → Create token).

Install

git clone https://github.com/qubit999/ha-mcp.git
cd ha-mcp
npm install
npm run build

This produces dist/index.js - the executable the clients launch.

Configuration

The server reads two environment variables:

Variable

Default

Description

HASS_URL

http://localhost:8123

Base URL of your Home Assistant instance

HASS_TOKEN

(required)

A long-lived access token

The same token authenticates both the REST calls and the WebSocket (used for the area registry). For local development you can drop these in a .env file and run npm run dev.

Connect a client

All three clients launch the server locally over stdio. Use the absolute path to dist/index.js.

Download the latest ha-mcp.mcpb from the Releases page (no build step needed), or build it yourself with npm run bundle.

Then in Claude Desktop: Settings → Extensions → Install Extension… (or just drag ha-mcp.mcpb into the window). Claude shows a form for Home Assistant URL and token (the token is masked and stored in your OS keychain), then launches the server for you. Restarting the app or re-pasting config is not needed.

Claude Desktop - manual (alternative)

If you'd rather not bundle, edit the config directly - Settings → Developer → Edit Config opens the file (path: ~/Library/Application Support/Claude/claude_desktop_config.json - note the space in "Application Support", so quote it in a shell). Add the block below and fully quit + relaunch the app:

{
  "mcpServers": {
    "ha-mcp": {
      "command": "node",
      "args": ["/Users/alex/ha-mcp/dist/index.js"],
      "env": {
        "HASS_URL": "http://localhost:8123",
        "HASS_TOKEN": "your-long-lived-token"
      }
    }
  }
}

Claude Code

claude mcp add ha-mcp \
  --scope user \
  --env HASS_URL=http://localhost:8123 \
  --env HASS_TOKEN=your-long-lived-token \
  -- node /Users/alex/ha-mcp/dist/index.js

Verify with claude mcp list / claude mcp get ha-mcp.

Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.ha-mcp]
command = "node"
args = ["/Users/alex/ha-mcp/dist/index.js"]
env = { HASS_URL = "http://localhost:8123", HASS_TOKEN = "your-long-lived-token" }

Then ask: "Turn on the kitchen light" or "What's the temperature in the living room?"

Security

A long-lived token grants full control of your Home Assistant (and thus your home). This server is designed to run locally over stdio - the client launches it as a subprocess; no network port is opened and the token never leaves your machine. Keep the token out of version control (the included .gitignore excludes .env). If you scope it into a shared .mcp.json, use a non-admin HA user or environment variables instead. There is intentionally no remote/HTTP transport here.

Development

npm run dev      # run from source with tsx (+ .env)
npm run build    # type-check and emit dist/

Tools are thin wrappers over src/ha.ts (REST helpers + a short-lived WebSocket client for the registries). The WebSocket connection is opened per registry fetch and cached briefly - there's no long-lived socket to manage.

License

MIT © qubit999

Available Tools

9 tools
ha_call_serviceB

Call any Home Assistant service. Examples: light.turn_on, climate.set_temperature, automation.trigger, scene.turn_on, media_player.play_media. Pass extra params (brightness, temperature, etc.) in data.

Inputs: domain (required), service (required), data, entity_id.

ha_get_configA

Get Home Assistant configuration: version, location, unit system, time zone, loaded components.

Inputs: no named parameters.

ha_get_entities_by_areaA

List the entity_ids in a given area/room (by name or area_id), resolving device→area inheritance.

Inputs: area (required).

ha_get_entityB

Get the full state and attributes of one entity by entity_id (e.g. 'light.kitchen_lights').

Inputs: entity_id (required).

ha_get_error_logA

Get the Home Assistant error log (plain text) for troubleshooting.

Inputs: no named parameters.

ha_get_historyA

Get state-change history for an entity over the last N hours (default 24).

Inputs: entity_id (required), hours.

ha_get_statesA

List Home Assistant entity states. Optionally filter by domain (e.g. 'light', 'sensor') and/or area (room name or area_id).

Inputs: area, domain.

ha_list_areasA

List all areas/rooms defined in Home Assistant.

Inputs: no named parameters.

ha_render_templateB

Render a Home Assistant Jinja2 template and return the result. Example: "{{ states('sensor.outside_temperature') }}".

Inputs: template (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 9 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: service calls, configuration retrieval, entity queries by area or ID, error logs, history, state listing, area listing, and template rendering. No overlap in functionality.

    Naming Consistency5/5

    All tools follow a consistent 'ha_{verb}_{noun}' pattern with underscores, using verbs like 'call', 'get', 'list', and 'render'. The prefix 'ha_' identifies the server, and naming is predictable.

    Tool Count5/5

    With 9 tools covering essential Home Assistant operations (service calls, state queries, configuration, history, error logs, areas, and template rendering), the count is well-scoped for an MCP server without being excessive.

    Completeness5/5

    The tool set covers core Home Assistant interactions: calling any service, retrieving states, config, history, error logs, and area information. The inclusion of template rendering adds flexibility. No obvious gaps for common tasks.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      A Model Context Protocol server that enables AI assistants like Claude to interact directly with Home Assistant, allowing them to query device states, control smart home entities, and perform automation tasks.
      29
      353
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      An MCP server and Home Assistant add-on that enables AI assistants to manage smart homes by creating automations, designing dashboards, and interacting with entities. It features native access to Home Assistant APIs, built-in Git versioning for safe rollbacks, and full management of HACS integrations.
      657
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      MCP server for full Home Assistant control, enabling AI agents to manage dashboards, automations, files, apps, entities, and more via REST API, WebSocket, and SSH.
      66
      151 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      An MCP server that enables AI assistants to control Home Assistant via natural language, including device control, automation management, and system configuration.
      MIT