ha-mcp
Provides full Home Assistant control including reading entity states, calling services, querying history, rendering templates, and resolving rooms/areas.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ha-mcp turn off the living room lights"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
| List entity states; optional |
| Full state + attributes for one |
| Call any service ( |
| State-change history for an entity over the last N hours |
| Render a Jinja2 template against live state |
| HA version, location, unit system, components |
| The error log, for troubleshooting |
| All areas/rooms |
| Entities in a room, resolving device→area inheritance |
Listing automations is just
ha_get_statesfiltered toautomation.*; triggering one isha_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 buildThis produces dist/index.js - the executable the clients launch.
Configuration
The server reads two environment variables:
Variable | Default | Description |
|
| Base URL of your Home Assistant instance |
| (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.
Claude Desktop - one-click (recommended)
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.jsVerify 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 toolsha_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
Scored across 9 tools
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.
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.
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.
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
Related MCP Connectors
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
MCP server that lets your AI assistant build and deploy apps, hosting each one at a live URL.
A TypeScript MCP server for Home Assistant, enabling programmatic management of entities, automati…
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Related MCP Servers
- AlicenseAqualityBmaintenanceA 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.29353MIT
- AlicenseNot gradedqualityBmaintenanceAn 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.657MIT
- AlicenseBqualityDmaintenanceMCP server for full Home Assistant control, enabling AI agents to manage dashboards, automations, files, apps, entities, and more via REST API, WebSocket, and SSH.66151 npmMIT
- AlicenseNot gradedqualityCmaintenanceAn MCP server that enables AI assistants to control Home Assistant via natural language, including device control, automation management, and system configuration.MIT