home-assistant-mcp — Claude Code MCP server for Home Assistant
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.
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-mcpWhat home-assistant-mcp 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.
What it helps with
- 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 for the agent
- Inspect my Home Assistant and build automations for radiator climate control
- Refactor
automations.yamland merge the duplicate automations - Add temperature history cards for each room to my dashboard
How to install home-assistant-mcp
Platform CLI
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-mcpReplace <…> with your own values
Platform CLI
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-mcpReplace <…> with your own values
Config file
{
"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
Config file
{
"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
Platform CLI
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-mcpReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about home-assistant-mcp
How do I install home-assistant-mcp in Claude Code?
Run 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 the placeholders with your agent URL and key.
What does home-assistant-mcp do?
It gives your AI editor access to Home Assistant: reading configuration and entities, creating automations, scripts and helpers, working with dashboards and themes, analysing logs, and installing HACS integrations.
What do I need before installing home-assistant-mcp?
A running Home Assistant, the HA Vibecode Agent add-on v2.2.0+ with its Agent Key, and Node.js v20.0.0 or higher on the computer where your editor runs.
