Home Assistant AI Helper: Secure MCP Server + Lightweight Add-on with Visual Dashboard Previews & Auto-Snapshots

Share your Projects!
, ,
1

Hi all,

I’ve put together an open-source Model Context Protocol (MCP) server and companion Home Assistant OS Add-on called ha-ai designed to let AI coding agents (Claude Desktop, Cursor, Antigravity, OpenCode) interact with Home Assistant safely.

Why Another Integration?

Most LLM setups for Home Assistant either require raw SSH/terminal access or struggle with visual validation. I wanted something that:

  1. Keeps the Home Assistant host lightweight (no Chromium/browser binaries on the server).
  2. Prevents accidental configuration loss or credential leaks.
  3. Allows multimodal models to visually verify Lovelace card designs.

Architecture & Safety Highlights

  • Lightweight Host Footprint: The Add-on is a standalone Python FastAPI daemon (< 50MB RAM, zero idle CPU) compiled for linux/arm64 and linux/amd64.
  • Path Traversal Jail: File operations are strictly locked to /config / /homeassistant.
  • Protected Secrets: Access to secrets.yaml, .storage/core.auth, SSH keys, and certificates is denied at the API boundary (403 Forbidden).
  • Atomic Pre-Edit Snapshots: Every write operation automatically creates a timestamped backup in /config/.snapshots/ before writing to disk, with 1-click rollback support.
  • Client-Side Playwright Rendering: Screenshots for visual feedback are rendered on your local workstation where the MCP client runs, offloading all browser rendering load from the HA machine.
  • Log Redaction: Automatic regex filtering redacts API keys, long-lived tokens, and passwords from log tails.

image
image1258×791 39.2 KB

Quick Setup

  1. Install the Add-on: Add this repository to your Add-on Store:

    https://github.com/sserhii-tech/home-assistant-mcp

Or use the one-click link:

Open your Home Assistant instance and show the add add-on repository dialog with a specific repository URL pre-filled.

  1. Configure an api_key in the Add-on configuration tab and start it.

  2. Configure your MCP Client (e.g., Claude Desktop claude_desktop_config.json):

     {
  "mcpServers": {
    "ha-ai": {
      "command": "node",
      "args": \["/path/to/home-assistant-mcp/mcp-server/dist/index.js"\],
      "env": {
        "HA_URL": "http://<YOUR_HA_IP>:8123",
        "HA_TOKEN": "<YOUR_LONG_LIVED_ACCESS_TOKEN>",
        "ADDON_URL": "http://<YOUR_HA_IP>:8099",
        "ADDON_KEY": "<YOUR_ADDON_API_KEY>"
      }
    }
  }
}

Links & Docs

Feedback, ideas, and contributions are very welcome!

2

Probably more in the Git Repo, I didn’t look… (home-assistant-mcp/docs/setup-guide.md at 3d54cbb91caf5ff19b569f949829d66d04ce6d2e · sserhii-tech/home-assistant-mcp · GitHub)

Add-ons are no longer a thing for over a year. They are called Apps now. I have been asking all new App authors to convert their stuff over so that the links work for install and the terms are correct. This especially helps new users that have never heard of Add-ons.
Also it is a great idea to test exactly what you are providing for installation instructions and make sure it works. If you don’t get that right, how can we trust that you coded the thing correctly. I do take your word that you coded this, as I do not see any AI attributions in the Git Repo as to anyone or anything else contributing to this release. Attributions to contributions are kinda required…

3

Add-ons are no longer a thing for over a year. They are called Apps now. I have been asking all new App authors to convert their stuff over so that the links work for install and the terms are correct. This especially helps new users that have never heard of Add-ons.

Will fix, thanks! Fixed, thanks!

Also it is a great idea to test exactly what you are providing for installation instructions and make sure it works. If you don’t get that right, how can we trust that you coded the thing correctly.

It is running on my instance right now, I used it to fix a few particularly flaky automations, working well for me so far.
As for the “trust I coded it well”, well… there’s code, you can review it (I would encourage anyone to!). And it is covered by tests - both TS MCP server, and FastAPI/Python App code. Is there a specific requirement I need to know? This is my first attempt on building the App in HA, so my apologies if I am missing some guidelines.

Attributions to contributions are kinda required…

No one else contributed to this repository. Yet, I hope :). But I did use AI to help me write the documentation. Do i need to mention it somewhere?

4

No, just if there was significant code help beyond syntax checking as I understand it.
Thanks for your contributions to Home Assistant!

5

The MCP + HA space is filling up fast, so the design question worth getting right early is differentiation at the identity layer, not just the action layer.

A pattern some teams are exploring is treating the AI agent itself as a named principal in the HA permission model, so automations can be scoped per agent rather than per token. If you have multiple agents hitting the same MCP server (a voice assistant, a scheduled routine, a debug session), HA logs can show which agent did what, and you can revoke or sandbox one without affecting the others.

For ha-ai specifically, I’d ask whether the server passes agent identity context through to HA today, or whether it’s effectively a shared credential. That single design call opens a lot of UX surface later: per-agent scenes, audit trails, guest agent access.

6

Interesting idea.

I built this MCP with end-to-end Lovelace dashboard building and automation debugging in mind. It uses a long-lived access token for Home Assistant’s REST/WS APIs, and a read-write config mount in the companion app for configuration and dashboard editing.

So effectively, it uses shared credentials, and Home Assistant itself doesn’t distinguish which sub-agent triggered a specific service call (though the app does create timestamped snapshot backups before every file edit).

You gave me some good food for thought, thanks!