Skip to main content
Glama
Devitek

mcp-ha

by Devitek
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
TypeScript
Local

mcp-ha: an MCP server for Home Assistant, as an add-on

CI Release MIT License

This Home Assistant add-on exposes an MCP (Model Context Protocol) server. In practice: you connect Claude, Gemini or any other MCP client to your instance, and you talk to your home.

"Which lights were left on?", "Why didn't the heating automation trigger last night?", "Plot my energy usage for the week."

Documentation: devitek.github.io/mcp-ha (English and French)

What it covers

Domain

Tools

Entities, areas, devices

fuzzy search, paginated lists, full details

Services

catalog per domain, search, guarded call (opt-in)

Automations

list, state, last trigger, full configuration, execution traces, guarded creation (opt-in)

Diagnostics

health report, execution traces, causality chains (why did this fire?)

Scripts

list, running state

History

state changes, long-term statistics, logbook

Energy

dashboard-backed totals and period comparisons

Presence

who is where, zone timeline (zones only, never coordinates)

Helpers

create and delete input_*, counters, timers (opt-in)

Notifications

send to phones and notify targets (opt-in, rate capped)

Announcements

speak on satellites and media players (opt-in, rate capped)

Scenes

snapshot the current mood as a scene (opt-in, volatile)

Weather

current conditions and forecasts (hourly, daily)

Calendar and to-do

events over a window, list items, guarded item management (opt-in)

Cameras

still snapshots as images (opt-in)

Add-ons

list and details (read)

System

Jinja template rendering, HA config, error log

Dashboards

list views, guarded card insertion (opt-in)

45 tools (27 read, 18 guarded write), designed to save the LLM context window: compact, paginated and capped responses, with notes that steer the assistant towards more precise queries.

Why not the official HA MCP integration?

It exists and works, but it goes through the Assist API: only entities exposed to Assist, no history, no registries, no add-ons, no automation configs. This add-on gives direct, granular access. Both can coexist.

Installation

Requirements: Home Assistant OS or Supervised (the add-on needs the Supervisor).

  1. Add this repository to your add-on repositories:

    Add repository

    Or manually: Settings, Add-ons, Add-on store, three-dot menu, Repositories, then paste https://github.com/Devitek/mcp-ha.

  2. Install "MCP Home Assistant" and start it.

  3. Open the add-on Configuration tab: an API token was generated and saved there on first start (the log only ever shows a masked prefix).

Connecting a client

Claude Code:

claude mcp add --transport http home-assistant \
  http://HA_IP:9583/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

Claude Desktop and Gemini CLI: see the clients guide on the documentation site.

Security, in short

  • Read only by default. The service-call tool does not even exist for the client unless you enable allow_write.

  • Defense in depth when writes are enabled: denylist of dangerous services (HA shutdown, shell_command...), glob allow/deny lists for entities, dry_run mode, JSON audit trail of every attempt in the log.

  • LAN only. No TLS, no OAuth: do not expose port 9583 to the internet.

The full threat model is in SECURITY.md.

Documentation

License

MIT