Home Assistant AI Helper (ha-ai)

Lightweight, paranoid-secure Home Assistant MCP Server and OS Add-on with client-side Playwright visual feedback for autonomous AI agents.

Overview

The ha-ai platform enables autonomous AI coding agents (such as Antigravity, Gemini CLI, Claude Code, OpenCode, and Cursor) to safely inspect, configure, iterate on, and visually validate a remote Home Assistant instance.

Primary Capabilities

• 👁️ Visual Dashboard Iteration: Render Lovelace dashboards headlessly via client-side Playwright, capture full or card-level screenshots across desktop, tablet, and mobile viewports, and visually iterate until UI design is perfected.

• ⚡ Full Lifecycle Automation & Script Authoring: Safely read, write, validate, and trigger automations and scripts with automatic syntax checks and zero-downtime service reloads.

• 🛡️ Paranoid Security: Strict path jailing within /config, constant-time API key verification, automatic secret redaction, and zero unauthorized command execution.

• 🪶 Minimal Server Footprint: Lightweight Python FastAPI container running as a Home Assistant OS Add-on (< 35MB RAM, ~0% idle CPU) with zero heavy browser or ML dependencies on the HA host.

• 🔄 Atomic Snapshots & One-Click Rollback: Automatic pre-edit snapshots created before every file modification, with instant atomic rollback capabilities.

Related MCP server: pagelens

Architecture

flowchart TD
    subgraph Workstation["Local Workstation / AI Agent Host"]
        Agent["AI Coding Agent<br/>(Antigravity / Claude / OpenCode)"]
        MCPServer["Local MCP Server<br/>(TypeScript / Stdio)"]
        Renderer["Playwright Browser Engine<br/>(Client-Side Headless)"]
        
        Agent <-->|"Model Context Protocol"| MCPServer
        MCPServer -->|"Render Requests"| Renderer
    end

    subgraph HAHost["Remote Home Assistant OS Instance"]
        HACore["Home Assistant Core<br/>(REST & WebSocket APIs)"]
        Addon["AI Helper Add-on<br/>(FastAPI / Alpine Container)"]
        Storage["HA Filesystem (/config)<br/>- automations.yaml<br/>- ui-lovelace.yaml<br/>- .snapshots/<br/>- home-assistant.log"]
        
        Addon -->|"Mounts rw"| Storage
    end

    MCPServer <-->|"HTTPS / WSS :8123"| HACore
    MCPServer <-->|"HTTP :8099 (X-Addon-API-Key)"| Addon
    Renderer -.->|"HTTP/S (Render Web UI)"| HACore

Security & Safety Highlights

Quickstart

1. Prerequisites

• Node.js 20+ and npm installed locally.

• Python 3.11+ with uv (for running add-on tests locally).

• Running Home Assistant OS instance.

2. Installation & Build

# Clone the repository
git clone https://github.com/sergii-shevchenko-ultimaker/home-assistant-mcp.git
cd home-assistant-mcp

# Install root dependencies
npm install

# Build the TypeScript MCP server
npm run build

3. Developer Workflows & Commands

# Local Development: Start Add-on daemon with hot-reloading on :8099
npm run dev:addon

# Local Development: Start MCP server in TypeScript watch mode
npm run dev:mcp

# Run full test suites (TypeScript Vitest & Python Pytest)
npm test
npm run test:addon

# Synchronize versions across all manifests and code atomically
npm run version:bump patch   # e.g. 0.1.0 -> 0.1.1
npm run version:bump minor   # e.g. 0.1.0 -> 0.2.0
npm run version:bump 1.0.0   # explicit version target

MCP Tools Reference

The server exposes 12 specialized tools under the Model Context Protocol:

📊 Dashboard Tools

⚙️ Automation & Script Tools

🛠️ System, Diagnostics & Safety Tools

AI Skill Pack (skills/)

This repository includes production-ready AI agent skills:

• 🎨 ha-dashboard-designer: Standard Operating Procedure for entity discovery, Lovelace card drafting, responsive layout verification, and iterative screenshot-based visual feedback loops.

• 🔧 ha-automation-builder: Standard Operating Procedure for drafting automations, validating trigger conditions, safe saving with automatic reloads, and log trace verification.

• 🚨 ha-troubleshooter: Safety SOP for diagnosing integration errors, analyzing sanitized logs, and triggering immediate rollback restorations.

Documentation

For full installation instructions, add-on configuration, agent integration guides (Antigravity, Gemini CLI, Claude Desktop, OpenCode, Cursor), and network architecture details, see:

📖 Full Installation & Setup Guide

License

This project is licensed under the Apache License, Version 2.0. See LICENSE for details.