HA Vibecode Agent: an MCP server that runs inside Home Assistant

The problem HA Vibecode Agent targets: SSH-based MCP integrations

Most MCP servers for Home Assistant run on your laptop and reach the instance over SSH, sometimes with the REST API bolted on. The project's README argues this is the wrong shape: because Home Assistant exposes internal APIs, runtime state and service calls that are easier to reach from inside the instance itself, an SSH client ends up generating temporary helper scripts per request. Those scripts change between runs, which makes the behaviour hard to repeat and hard to review.

That is a fair criticism of the pattern, not just of one implementation. If the model writes a throwaway script to enumerate entities, you cannot diff it, you cannot cache it, and the next request writes a different one. HA Vibecode Agent replaces that with a fixed tool surface. The audience is narrow and clear: people who already run Claude Code, Cursor, VS Code or another MCP-capable IDE and want it to touch a live Home Assistant rather than produce YAML they paste in by hand.

Two processes, one API: the Agent and the MCP server

The repository is split into two modules. The Home Assistant Agent runs inside or alongside Home Assistant and holds native access to files, entities, services and runtime state. The MCP server runs on your computer next to the IDE and talks to the Agent over a controlled HTTP API. The IDE never sees your Home Assistant directly.

The stated benefit is context efficiency. Rather than loading full YAML files, entity dumps or logs into the prompt, the Agent is expected to return only what is relevant: selected entities, service definitions, automation fragments, validation results or structured errors. That is the real design claim, and it is testable by watching how much of your config ends up in the model's context. The repository layout backs the two-module story: app/ holds the service, Dockerfile builds the add-on image from a BUILD_FROM argument, Dockerfile.standalone and docker-compose.standalone.yml cover the container path, and run.sh is the add-on entrypoint. A separate npm package, @coolver/home-assistant-mcp, is published for the MCP side.

Installing the add-on and connecting Cursor

The default path assumes Home Assistant OS or Supervised, because the add-on needs the Supervisor API for add-on management. In the Home Assistant UI, go to Settings, then Add-ons, then the Add-on Store, open the overflow menu and pick Repositories. Add the repository URL:

https://github.com/coolver/home-assistant-vibecode-agent

Refresh the page, find HA Vibecode Agent in the store and install it. The README says to wait for installation, set Start on boot to ON, press START and allow roughly ten seconds for startup. Then click Open Web UI. That ingress panel is where the rest of the setup lives: pick the Cursor or VS Code tab and follow the instructions shown there to wire the IDE to the Agent over MCP.

For HA Container, Proxmox or NAS installs there is no Supervisor, so the standalone mode applies. The repository ships .env.example for it:

HA_URL=http://192.168.1.100:8123
HA_TOKEN=your_long_lived_access_token_here
HA_CONFIG_PATH=/path/to/homeassistant/config
PORT=8099
GIT_VERSIONING_AUTO=true
MAX_BACKUPS=30

HA_TOKEN is a long-lived access token created under Profile, then Long-Lived Access Tokens. HA_CONFIG_PATH points at the config directory on the host, and the agent listens on 8099 by default. The Dockerfile health check polls http://localhost:8099/api/health, so that endpoint is the quickest way to confirm the container came up.

What standalone mode gives up

The README is explicit that both deployment modes share the same core functionality and that the only difference is add-on management. Installing, uninstalling or restarting add-ons requires the Supervisor, so a Docker or Proxmox user cannot ask the agent to do it. That is a real boundary rather than a bug, but it is easy to miss when reading the feature list, which mentions HACS integrations and custom repositories alongside automations and dashboards.

The other boundary is the token. Standalone mode needs a long-lived access token and a host path to the config directory, which means the process can read and write your Home Assistant configuration. There is no separate scoped credential described in .env.example. If you would not hand that combination to a background service, the add-on path at least keeps the agent inside the Supervisor's managed environment, but the access is still broad.

Git versioning and what it does not promise

The README lists "safely deploy changes with automatic Git-based versioning" among the capabilities, and .env.example exposes GIT_VERSIONING_AUTO, defaulting to true, plus MAX_BACKUPS, defaulting to 30. So the intended safety net is a commit before or after a change, with a bounded history of backups. The repository also contains restore_config_files.py at the top level, which suggests a restore path exists.

What the README does not document is rollback as a user-facing operation, nor how a restore is triggered, nor what happens when the config directory is not already a Git repository. Those are the questions to answer before letting the agent write to a production instance. Treat the Git layer as a backup mechanism whose exact semantics you verify yourself, not as a documented undo button. The CHANGELOG.md file is the place to check for behaviour changes between versions, since the README carries a version badge but no release history.

How it compares with a plain Home Assistant MCP server over SSH

The obvious alternative is a local MCP server that connects to Home Assistant over SSH and the REST API, running entirely on your machine. The difference is where the intelligence sits. An SSH-based server has to reconstruct Home Assistant's view of the world from the outside, which is why the README describes it as generating helper scripts per request. HA Vibecode Agent pushes that work into the instance, where the APIs and state already live, and exposes a fixed tool surface upward.

The trade-off is deployment weight. A local MCP server is one process on your laptop and nothing on the Home Assistant host. HA Vibecode Agent is two processes, an add-on or container to keep updated, a port, and a token with write access to your config. You are trading a lighter install for a more predictable and more context-efficient one. If your Home Assistant is a throwaway test instance, the lighter option wins. If it is the thing running your house, the argument for a stable API over ad-hoc scripts is stronger.

Licence and upgrade cost

The project is MIT licensed, which permits commercial and private use, modification and redistribution provided the copyright notice and permission notice are retained. The README and repository metadata both state MIT, and a LICENSE file sits at the top level. Nothing described in the README points to a separate enterprise tier, a hosted service or a paid component, so there is no licence gate on features. This is not legal advice; read the LICENSE file if you plan to redistribute.

Upgrade cost is the part to weigh honestly. The add-on updates through the Home Assistant add-on store, and the MCP side is an npm package, @coolver/home-assistant-mcp, which means two version streams that can drift apart. The Dockerfile header carries its own version comment and build timestamp, distinct from the README badge, which is a hint that the images and the source are versioned separately. Pin the MCP package version in your IDE configuration and check CHANGELOG.md before moving the add-on, because a mismatch between the two halves is the failure mode this split architecture invites.

Editorial conclusion

Adopt it if you already drive Home Assistant through Claude Code, Cursor or VS Code and you want the model to see real entity state rather than guess at YAML. Skip it if you run a plain HA Container install and need add-on management, since that path requires the Supervisor, or if you are unwilling to give an external process a long-lived access token and write access to your config directory. Before trusting it on a production instance, verify what the Git versioning actually commits by reading the GIT_VERSIONING_AUTO and MAX_BACKUPS defaults in .env.example, and confirm the agent's port 8099 is not reachable from outside your LAN.

Frequently asked questions

Official sources

1. Coolver/home-assistant-vibecode-agent on GitHub
2. Issues
3. License: MIT
4. Project website
5. README