Home Assistant AI Helper (ha-ai)

Lightweight, paranoid-secure Home Assistant MCP Server and OS App 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 App (< 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 App<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 app tests locally).

• Running Home Assistant OS instance.

2. Installation & Build

# Clone the repository
git clone https://github.com/sserhii-tech/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 App 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 4 production-ready AI agent skills:

• 🎮 ha-device-controller: Standard Operating Procedure for querying entity states, executing domain service requests (lights, switches, climate, media), and verifying post-execution state transitions.

• 🎨 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, app 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.