# home-assistant-mcp

Connects your IDE to Home Assistant through an add-on agent: the AI reads your config, writes automations, dashboards and themes, then deploys with Git versioning.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 58
- Author: Coolver
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/Coolver/home-assistant-mcp
- Updated: 2026-10-21
- HTML: https://affpapa.org/en/nevibecode/mcp/home-assistant-mcp

## What it does

The server pairs with HA Vibecode Agent, which runs as an add-on inside Home Assistant and reaches the internal APIs, files and services. The MCP server itself sits on your computer next to the editor and talks to the agent over an API instead of SSH. From the IDE you can read entities, automations, scripts and helpers, build new automations and sensors around your actual devices, refactor what you already have, create and rearrange Lovelace dashboards, adjust themes, check logs, and install HACS integrations.

You need Home Assistant running, HA Vibecode Agent v2.2.0+ installed as an add-on, and the Agent Key it generates on first start. Node.js goes on the machine with the editor, not on the Home Assistant host — the server starts through `npx`, and anything below v20.0.0 will not run it. Without the agent URL and key there is nothing to connect to, so both values have to be set as environment variables.

Every change lands in Git with readable commit messages. Configuration is validated before it is applied, and you can roll back to an earlier state. That matters once you have a pile of automations and edit them often.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `HA_AGENT_URL`, `HA_AGENT_KEY` — keys and tokens: ask the human for the values, never commit them or put them in shared files.
- Works with: Home Assistant

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add home-assistant-mcp -e HA_AGENT_URL=<HA_AGENT_URL> -e HA_AGENT_KEY=<HA_AGENT_KEY> -- npx -y @coolver/home-assistant-mcp
```
Replace <…> with your own values

### Codex

**Platform CLI**
```bash
codex mcp add home-assistant-mcp --env HA_AGENT_URL=<HA_AGENT_URL> --env HA_AGENT_KEY=<HA_AGENT_KEY> -- npx -y @coolver/home-assistant-mcp
```
Replace <…> with your own values

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "home-assistant-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "@coolver/home-assistant-mcp"
            ],
            "env": {
                "HA_AGENT_URL": "<HA_AGENT_URL>",
                "HA_AGENT_KEY": "<HA_AGENT_KEY>"
            }
        }
    }
}
```
Replace <…> with your own values

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "home-assistant-mcp": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "@coolver/home-assistant-mcp"
            ],
            "env": {
                "HA_AGENT_URL": "<HA_AGENT_URL>",
                "HA_AGENT_KEY": "<HA_AGENT_KEY>"
            }
        }
    }
}
```
Replace <…> with your own values

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e HA_AGENT_URL=<HA_AGENT_URL> -e HA_AGENT_KEY=<HA_AGENT_KEY> home-assistant-mcp npx -y @coolver/home-assistant-mcp
```
Replace <…> with your own values

## When to use it
- build automations around your real devices and sensors
- merge and refactor existing automations instead of starting over
- rearrange a Lovelace dashboard by room
- restyle the UI theme without hand-editing YAML
- read logs to find why an automation failed

## Example prompts
- Inspect my Home Assistant and build automations for radiator climate control
- Refactor `automations.yaml` and merge the duplicate automations
- Add temperature history cards for each room to my dashboard

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 386989
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119160
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47392
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43872

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md