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 automation.morning.
Validate this YAML: automation:\n  - alias: Kitchen lights

For tools with a required ID or value, include it in the prompt. For example, say Diagnose dashboard lovelace-main or Search Home Assistant configuration for Tesla. Review the result before running transaction commit or repair commands.

Docker

# Build and run with docker-compose
docker-compose up -d

# Or build manually
docker build -t ha-mcp .
docker run -e HA_URL=http://homeassistant:8123 -e HA_TOKEN=your-token ha-mcp

Home Assistant Add-on

You can install this as a Home Assistant Add-on:

1. In Home Assistant, go to Settings → Add-ons → Add-on Store
2. Click the menu (three dots) → Repositories
3. Add this repository URL
4. Find HA MCP Server and click Install
5. Configure your HA_URL and HA_TOKEN
6. Start the add-on

The add-on runs as a service on the same network as Home Assistant and exposes the MCP interface over stdio.

Available MCP Tools

Use the command name in Copilot Chat, followed by its required values. Empty arguments mean the command can be run without parameters.

Entity and system health

Command	Required arguments	Example VS Code chat prompt
health_score	None	Run health_score.
full_system_diagnosis	None	Run a full system diagnosis.
analyze_entity_health	entity_id	Analyze entity health for sensor.living_room_temperature.
find_unused_entities	None	Find unused entities.
get_entity_dependencies	entity_id	Show dependencies for light.kitchen.
search_configuration	query	Search configuration for Tesla charging.
build_context	problem; optional scope	Build context for why lights are unavailable, scoped to lighting.

Automations, dashboards, scenes, and configuration

Command	Required arguments	Example VS Code chat prompt
analyze_automation	automation_id	Analyze automation automation.morning.
simulate_automation	automation_id	Simulate automation automation.morning.
find_broken_automations	None	Find broken automations.
diagnose_dashboard	dashboard_id	Diagnose dashboard lovelace-main.
validate_dashboard_yaml	yaml_content	Validate this dashboard YAML: <YAML content>.
find_broken_dashboards	None	Find broken dashboards.
repair_dashboard	dashboard_id	Repair dashboard lovelace-main.
analyze_scene	scene_id	Analyze scene scene.evening.
validate_template	template_string	Validate template {{ states('sensor.temperature') }}.
explain_template	template_string	Explain template {{ is_state('binary_sensor.door', 'on') }}.
validate_yaml	path_or_content	Validate this YAML: <YAML content>.

Integrations and events

Command	Required arguments	Example VS Code chat prompt
diagnose_integration	domain	Diagnose the mqtt integration.
list_integrations	None	List installed integrations.
find_unhealthy_integrations	None	Find unhealthy integrations.
subscribe_events	filter; optional duration	Subscribe to automation events for 60 seconds.
replay_events	filter, since	Replay state-change events since 2026-08-01T00:00:00Z.

Repair and transactions

Command	Required arguments	Example VS Code chat prompt
repair_system	None	Run a system repair scan.
transaction_begin	description	Start a transaction to update kitchen automation.
transaction_stage	transaction_id, edit	Stage this edit in transaction <ID>: <edit object>.
transaction_diff	transaction_id	Show the diff for transaction <ID>.
transaction_validate	transaction_id	Validate transaction <ID>.
transaction_commit	transaction_id	Commit transaction <ID>.
transaction_verify	transaction_id	Verify transaction <ID>.
transaction_rollback	transaction_id	Roll back transaction <ID>.
transaction_status	transaction_id	Show the status of transaction <ID>.

The normal transaction sequence is: transaction_begin, transaction_stage, transaction_diff, transaction_validate, transaction_commit, then transaction_verify. Use transaction_rollback before committing when you need to discard staged changes.

Project Structure

src/ha_mcp/
├── __init__.py
├── app.py                    # Application orchestrator
├── config.py                 # Pydantic-settings configuration
├── logging_config.py         # Structlog configuration
├── models/                   # Frozen domain models
│   ├── graph_node.py
│   ├── observation.py
│   ├── finding.py
│   ├── recommendation.py
│   ├── staged_edit.py
│   ├── tool_result.py
│   ├── provider_protocol.py  # Provider Protocol with Capability enum
│   └── action.py
├── providers/                # Transport implementations
│   ├── base.py               # ProviderRegistry
│   ├── ha/                   # Home Assistant REST/WebSocket
│   ├── git/                  # Git operations via dulwich
│   ├── filesystem/           # Local filesystem
│   ├── docker/               # Docker SDK
│   ├── mqtt/                 # MQTT via aiomqtt
│   ├── logs/                 # Log file reading
│   └── events/               # Event streaming
├── modules/                  # Analysis modules
│   ├── entities/             # Entity health analysis
│   ├── automations/          # Automation diagnostics
│   ├── dashboards/           # Dashboard analysis
│   ├── diagnostics/          # System health score
│   ├── search/               # Configuration search
│   ├── scenes/               # Scene analysis
│   ├── templates/            # Template analysis
│   └── yaml/                 # YAML validation
├── graph/                    # GraphRepository Protocol + NetworkX impl
│   ├── graph_repository.py
│   └── graph_repository_impl.py
├── analysis/                 # Collector/Analyzer Protocols
│   └── pipeline.py
├── transaction/              # TransactionManager
│   └── transaction_manager.py
├── plugins/                  # Plugin system
│   ├── manifest.py
│   └── loader.py
└── server/                   # MCP stdio server
    └── __init__.py

Development

Running Tests

pytest tests/ -v

Adding a New Module

1. Create src/ha_mcp/modules/your_module/ with:

   • collector.py — implements Collector Protocol
   • analyzer.py — implements Analyzer Protocol
   • module.py — wires collector + analyzer + action
   • __init__.py

2. The module is auto-discovered by App.auto_register_modules()

3. Add MCP tool in src/ha_mcp/server/__init__.py

Adding a Plugin

1. Create a package with PluginManifest:

   from ha_mcp.plugins import PluginManifest
   
   manifest = PluginManifest(
       name="my-plugin",
       version="1.0.0",
       description="My custom plugin",
       author="Author",
       capabilities=frozenset({"read", "write"}),
       entry_point="my_plugin.module",
   )
   

2. Register in pyproject.toml:

   [project.entry-points."ha_mcp.plugins"]
   my-plugin = "my_plugin"
   

Architecture

See docs/02-architecture.md for the v2.2 architecture specification.

Key Constraints

• No LLM in core — all analysis is deterministic
• Single mutation path — Collector → Analyzer → Finding → Recommendation → Action → StagedEdit → TransactionManager
• Frozen domain models — GraphNode, Observation, Finding, Recommendation, StagedEdit are immutable
• Provider Protocol — all transports implement Provider with frozenset[Capability]
• Intent is internal — never exposed through MCP

Testing

# All tests
pytest tests/ -v

# Contract tests only
pytest tests/contract/ -v

# Unit tests only
pytest tests/unit/ -v

CI/CD

GitHub Actions runs tests on Python 3.11, 3.12, 3.13 and linting with ruff on every push and PR.

License

MIT