Home Assistant MCP

Official

by Coolver · TypeScript

Vibecode your Home Assistant setup from your IDE: automations, dashboards, themes and configs

Configure Home Assistant automations, dashboards, themes and settings from your IDE.

Home Assistant Vibecode MCP

⚙️ This MCP server works together with the
Home Assistant Vibecode Agent,
installed as a Home Assistant add-on.
The agent runs on your Home Assistant instance and provides “eyes and hands” for AI IDEs like Cursor, VS Code, Claude Code, or any other MCP-enabled IDE.

Let AI build your Home Assistant automations – or act as your DevOps for the ones you write by hand. Just describe what you need in natural language. 🏠🤖

You describe your goal → AI inspects your Home Assistant → designs a custom solution → and deploys it on-board automatically. 🚀

And if you prefer to handcraft your automations and scripts yourself, the agent can simply act as your DevOps and extra pair of hands: quickly uploading your changes, running tests, and analyzing logs on demand. You stay in control and decide how much you delegate to AI and how deep it should go.

Transform the way you manage your smart home. This add-on enables Cursor, Visual Studio Code (VS Code), or any MCP-enabled IDE to:

📝 Analyze your Home Assistant configuration, entities, and devices
🏗️ Create intelligent automations, scripts, and complete systems — including Home Assistant helpers that can be fully managed programmatically
🎨 Design and customize Lovelace dashboards with full control over cards, layouts, and styling
🖌️ Create and tweak themes for a personalized UI
🔄 Safely deploy changes with automatic Git-based versioning
🔍 Monitor and troubleshoot your setup through log analysis
📦 Install and manage HACS integrations and custom repositories

No more manual YAML editing or searching through documentation - just describe what you want in natural language!

Example: "Install smart climate control for my radiators" → AI creates 10+ automations, helpers, sensors, and scripts optimized for YOUR TRVs.

Built on Model Context Protocol and powered by HA Vibecode Agent.

✨ Key Features

🔍 Analyze your setup

✅ Read your full configuration — entities, automations, scripts, helpers
✅ Understand your devices — capabilities, relations, and usage patterns
✅ Learn existing logic — analyze how your current automations and scripts behave

🏗️ Build intelligence

✅ Create complete systems — multiple interconnected automations in seconds
✅ Generate helpers and sensors — tailored to your actual setup and needs
✅ Write optimized scripts — based on real entities, areas, and devices
✅ Refactor existing logic — improve or merge automations instead of starting from scratch

📊 Dashboards & UI

✅ Create and update Lovelace dashboards — fully programmatically
✅ Add, remove, or rearrange cards — stat, graphs, history, custom cards, and more
✅ Control layouts and views — organize rooms, areas, and scenarios
✅ Design and tweak themes — colors, typography, and styles for a personalized UI

🔒 Safe operations

✅ Git-based versioning — every change is tracked with meaningful commit messages
✅ Human-readable commits — AI explains what changed and why
✅ Configuration validation — test before apply to reduce breaking changes
✅ One-click rollback — revert to a previous state if something goes wrong
✅ Activity log — full audit trail of what the agent did and when

📦 Extend with the community

✅ Install and configure HACS — unlock 1000+ community integrations
✅ Search repositories — themes, plugins, custom components, dashboards
✅ Install integrations — one-command setup for new HACS components
✅ Keep things fresh — update all HACS repositories from a single place

Result:
You describe your goal → AI inspects your Home Assistant → designs a custom solution → and deploys it on-board automatically. 🚀

🚀 How is this different from other MCP modules for Home Assistant?

Most MCP integrations I’ve seen for Cursor, VS Code or Claude work only on your local machine and talk to Home Assistant over SSH and sometimes the REST API.

For serious Home Assistant work, that’s not really enough:

Home Assistant is not just a bunch of YAML files. It exposes multiple internal APIs, and some of the most important ones are only available from inside HA itself over the WebSocket API.

When you access HA only via SSH, the AI usually has to generate and upload a helper script on every request, then execute it blindly on the host. Since that script can be different every time, each request is a bit of a black box — more like playing Russian roulette than doing reliable automation.

Because of that, I chose a different architecture.

This project is split into two modules:

Home Assistant Agent (this module) – runs inside Home Assistant (as an add-on), has native access to all relevant APIs, files and services, and exposes a safe, well-defined interface for external tools.

Home Assistant MCP server – runs on your computer alongside your AI IDE (Cursor, VS Code, etc.) and talks to the Agent over a controlled API instead of SSH hacks (installation steps below)

This design makes working with Home Assistant faster, more predictable, safer and repeatable. Your AI IDE gets exactly the actions and data it needs — through a stable API — instead of constantly inventing ad-hoc scripts and hoping they behave correctly.

📋 Prerequisites

Before installing, you need:

Home Assistant running (any version)
HA Vibecode Agent v2.2.0+ installed as add-on
Agent Key from HA Vibecode Agent (auto-generated on first start)
AI-enabled editor installed (Cursor, VS Code + GitHub Copilot, Claude Code etc)

🚀 Quick Start (5 minutes)

Step 0: Install Node.js (if not already installed)

The MCP server requires Node.js to run on your computer (where your AI editor is installed):

Check if Node.js is already installed: open terminal and run node --version
If not installed or version is below v20.0.0, download and install from nodejs.org (use the 24.x LTS build when possible)
After installation, verify: node --version should show v20.0.0 or higher (v24 LTS recommended)
Important: Install Node.js on the computer where your AI editor runs, not on the Home Assistant server

Step 1: Install HA Vibecode Agent

Install the agent in your Home Assistant from :

Go to Settings → Add-ons → Add-on Store
Click ⋮ → Repositories
Add: https://github.com/Coolver/home-assistant-vibecode-agent
Install HA Vibecode Agent (v2.0.0+)
Start the agent

Step 2: Setup MCP in Your AI Editor

Get configuration from Home Assistant:

Open your Home Assistant (usually http://homeassistant.local:8123)
Go to Settings → Add-ons → HA Vibecode Agent
Click "Open Web UI" button
Click the Cursor or VS Code tab (depending on which IDE you want to use with Home Assistant) and follow the setup instructions. You’ll need to install and configure Cursor or VS Code so they can connect to the HA Agent via the MCP protocol.
That’s it — you’re ready to start working with your Home Assistant scripts, automations and dashboards using AI. If you find this project useful and want to support its development, please consider giving it a GitHub Star ⭐

Step 3: Test Connection

Verify everything works:

Open your AI editor (Cursor, VS Code, etc) and send this message to AI:

code

Connect to my Home Assistant and show me:
1. List of all my climate entities
2. Current status of the HA Vibecode Agent

This will verify the MCP connection is working.

If AI successfully returns your entities and agent status, you're all set! ✅

Troubleshooting: If connection fails:

Check that HA Vibecode Agent is running
Ensure your AI editor was fully restarted
Verify configuration was pasted correctly

Step 4: Start Building!

Just describe what you want in natural language - AI will handle the rest!

🔧 Configuration

Environment Variables

Variable	Description	Required	Default
`HA_AGENT_URL`	URL of HA Vibecode Agent	Yes	`http://homeassistant.local:8099`
`HA_AGENT_KEY`	Agent Key for authentication	Yes	-

Custom Agent URL

If your agent runs on a different URL:

json

{
  "mcpServers": {
    "home-assistant": {
      "command": "npx",
      "args": ["-y", "@coolver/home-assistant-mcp@latest"],
      "env": {
        "HA_AGENT_URL": "http://<home-assistant-host>:8099",
        "HA_AGENT_KEY": "your_api_key_here"
      }
    }
  }
}

🐛 Troubleshooting

"Invalid Agent Key" error

Check your Agent Key is correct in mcp.json (under HA_AGENT_KEY)
Regenerate key if needed: Settings → Add-ons → HA Vibecode Agent → Open Web UI
Make sure HA Vibecode Agent is running
Verify agent is accessible: curl http://homeassistant.local:8099/api/health

"Connection refused"

Check HA Vibecode Agent is started in Home Assistant
Verify the URL in HA_AGENT_URL
Make sure port 8099 is not blocked by firewall

"spawn npx ENOENT" error

This error means Node.js is not installed or not found in your system PATH.

Solution: Install Node.js (v20.0.0 or higher; v24 LTS recommended) on the computer where Cursor is running:

Download and install Node.js from https://nodejs.org
Restart Cursor completely after installation
Verify installation by running node --version in a terminal

Important: Node.js must be installed on your computer (where Cursor, VS Code, Claude or other IDE runs), not on the Home Assistant server.

🔐 Security

✅ All communication goes through HA Vibecode Agent (port 8099)
✅ Agent Key authentication for MCP clients
✅ Agent validates Agent Key for all requests
✅ Agent uses internal SUPERVISOR_TOKEN for Home Assistant API operations
✅ Your Agent Key is stored only in local IDE config file
⚠️ Never commit mcp.json with your Agent Key to git!

HA Vibecode Agent - Home Assistant add-on (required)
Model Context Protocol - Protocol specification

📝 License

🔧 Development

Project Structure

code

home-assistant-mcp/
├── package.json            # NPM package config
├── tsconfig.json           # TypeScript config
├── src/
│   ├── index.ts           # MCP server entry point
│   ├── ha-client.ts       # HA Agent API client
│   ├── handlers.ts        # Tool request handlers
│   ├── tools.ts           # Legacy tool definitions
│   └── tools/             # Modular tool definitions
│       ├── index.ts       # Tool exports
│       ├── files.ts       # File operation tools
│       ├── system.ts      # System operation tools
│       └── dashboard.ts   # Dashboard tools
├── build/                 # Compiled JavaScript output
├── README.md
├── CHANGELOG.md
└── QUICK_START.md

Architecture

MCP Server (index.ts) ← Communication Protocol
↓
Tool Handlers (handlers.ts) ← Business Logic
↓
HA Client (ha-client.ts) ← HTTP API Wrapper
↓
HA Vibecode Agent (https://github.com/Coolver/home-assistant-vibecode-agent) (REST API) ← Home Assistant Integration

🙏 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

💬 Support

🐛 Issues: GitHub Issues
💡 Discussions: GitHub Discussions

⭐ Show your support

Give a ⭐️ if this project helped you control your smart home with AI!

Install

Configuration

Environment variables

HA_AGENT_URLrequired

URL of your on-board Home Assistant Vibecode Agent add-on (generated after installation of the add-on)

HA_AGENT_KEYrequiredsecret

Access key generated by the Home Assistant Vibecode Agent add-on after installation

Add to VS Code Add to Cursor

claude_desktop_config.json