Home Assistant MCP Server

AI sysadmin for Home Assistant — analysis platform exposing diagnostics, automation health, entity monitoring, dashboard analysis, and configuration search via the Model Context Protocol.

Features

• Entity Health Analysis — detect stale/unavailable entities, unknown states, missing attributes
• Automation Diagnostics — find disabled automations, missing triggers, invalid configurations
• Dashboard Analysis — detect deprecated cards, missing views
• System Health Score — 0-100 health score across all entities
• Configuration Search — semantic search across entity IDs, friendly names, and states
• Scene Analysis — detect empty or misconfigured scenes
• Template Analysis — detect templates without Jinja2 syntax
• YAML Validation — detect empty or invalid YAML configurations
• Transaction Safety — staged edits with validate/commit/rollback/verify semantics
• Multi-Provider Support — HA REST/WebSocket, Git, Filesystem, Docker, MQTT, Logs, Events
• Plugin Ecosystem — manifest-driven plugin discovery via entry points

Requirements

• Python 3.11+
• Home Assistant instance (for HA provider functionality)
• pip/venv for installation

Installation

# Clone the repository
git clone <repository-url>
cd mcp_server_ha

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in editable mode with dev dependencies
pip install -e ".[dev]"

Configuration

The server is configured via environment variables or a config file passed to the HA provider.

Environment Variables

Variable	Description	Default
HA_URL	Home Assistant URL	http://homeassistant.local:8123
HA_TOKEN	Long-lived access token	(required for HA features)
HA_VERIFY_SSL	Verify SSL certificates	true

Example Configuration

config = {
    "ha": {
        "url": "http://homeassistant.local:8123",
        "token": "your-long-lived-access-token",
        "verify_ssl": True,
    }
}

Running the Server

As a Standalone MCP Server

# Start the MCP server (Streamable HTTP)
ha-mcp

# Or directly with Python
python -m ha_mcp.server

The server listens on http://localhost:8090/mcp using Streamable HTTP. Set HA_URL, HA_TOKEN, and optionally HA_VERIFY_SSL before starting it.

As a Library

import asyncio
from ha_mcp.app import App
from ha_mcp.providers.ha import HAProvider
from ha_mcp.modules.entities.module import EntitiesModule

async def main():
    app = App()
    provider = HAProvider()
    module = EntitiesModule(provider)
    
    app.register_provider(provider)
    app.register_module("entities", module)
    await app.initialize({"ha": {"url": "http://homeassistant.local:8123", "token": "..."}})
    
    result = await app.run_module("entities", requested_by="user")
    for finding in result.findings:
        print(f"[{finding.severity}] {finding.message}")
    
    await app.shutdown()

asyncio.run(main())

Connecting to MCP Clients

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "ha-mcp": {
      "command": "ha-mcp",
      "env": {
        "HA_URL": "http://homeassistant.local:8123",
        "HA_TOKEN": "your-long-lived-access-token"
      }
    }
  }
}

Claude Code (CLI)

claude --mcp "ha-mcp:ha-mcp"

Other MCP Clients

Any MCP-compatible client can connect to http://localhost:8090/mcp using Streamable HTTP.

VS Code

When the ha-mcp server is connected in VS Code, open Copilot Chat in Agent mode and ask for one of the commands below in plain language. Copilot selects the matching MCP tool and supplies the arguments from your request. For example:

Run health_score.
Find broken automations.
Analyze automation automat