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

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
Scripts	list, running state
History	state changes, long-term statistics, logbook
Add-ons	list and details (read)
System	Jinja template rendering, HA config, error log

16 tools in total, 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:

   

   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

• Documentation site: installation, configuration, clients, tool reference, architecture (English and French)
• LLM-friendly docs following the llms.txt convention: llms.txt (index) and llms-full.txt (everything in one file), also indexed on Context7
• Add-on documentation: the page shown in the HA interface
• Contributing guide: dev setup, conventions, releases
• Repository issues: the project knowledge base, every design decision and pitfall is tracked there with the décision and écueil labels (in French)

License

MIT