ha-mcp

A Model Context Protocol (MCP) server that provides AI assistants with access to Home Assistant, enabling smart home control and automation management.

Features

• 41 Specialized Tools: Entity queries, automation CRUD, helper management, scripts, scenes, devices, areas, labels, floors, zones, persons, tags, traces, blueprints, updates, todos, calendars, cameras, dashboards, system log, and more
• Hybrid Architecture: WebSocket for most operations, REST API for automation/script/scene CRUD
• Complete CRUD: Create, read, update, delete automations/scripts/scenes/helpers
• Deep System Access: Query registries, analyze dependencies, access logbook, validate config
• Flexible Output: Natural language (LLM-optimized) and JSON formats
• Access Control: Read-only mode, whitelist/blacklist, fine-grained action-level control
• Auto-Reconnect: Automatic reconnection with exponential backoff
• Post-Mutation Confirmation: Automatic state polling after create/update/delete confirms changes

vs. Other MCP Servers for Home Assistant

Two alternatives exist: the official HA MCP integration (built-in Core component, ~15 intent tools) and community homeassistant-ai/ha-mcp (Python/FastMCP, 88 tools).

Choose ha-mcp if you need:

• Full automation, script, scene, and helper lifecycle management (create, edit, delete)
• RFC 6902 and semantic JSON patching for automations and dashboards without full-file overwrites
• Helper management across 41 types, including multi-step config entry flows and template subtypes
• Deep diagnostics (blast-radius analysis, dependency graphs, cross-configuration reference search)
• Post-mutation state diffing (Smart Wait confirms `entity: off -> on` inline)
• Efficient LLM context usage: 41 consolidated tools consume ~3,500 tokens of schema space, compared to 15,000+ tokens for 88 separate tools
• Single static binary with zero runtime dependencies and low memory usage

Choose the official integration if you need basic device control with zero external setup, or strictly rely on Assist Voice exposure settings.

Choose community ha-mcp if you need in-HA execution via HACS or Add-on, human-in-the-loop approval policy queues, or entity concealment filters.

See docs/feature-comparison.md for a detailed three-way feature matrix.

Installation

From Binary

Download the latest release from the Releases page.

# Linux/macOS
tar -xzf ha-mcp_linux_amd64.tar.gz
chmod +x ha-mcp
sudo mv ha-mcp /usr/local/bin/

# Windows: extract ha-mcp_windows_amd64.zip and add to PATH

From Source

Requires Go 1.27 or later.

git clone https://github.com/zorak1103/ha-mcp.git
cd ha-mcp
task install-hooks  # install git pre-commit hook (auto-fixes gofmt on every commit)
task lint:install   # install golangci-lint built with your local Go toolchain
go build -o ha-mcp ./cmd/ha-mcp

Linux Packages

RPM and DEB packages are available in the releases:

sudo dpkg -i ha-mcp_amd64.deb   # Debian/Ubuntu
sudo rpm -i ha-mcp_amd64.rpm    # RHEL/Fedora

Docker

docker pull zorak1103/ha-mcp:latest
docker run -d --name ha-mcp -p 8080:8080 \
  -e HA_URL=http://homeassistant.local:8123 \
  zorak1103/ha-mcp:latest

See docs/configuration.md for Docker options, HTTPS/WSS, proxy support, and all environment variables.

Quick Start

1. Get a long-lived access token from your Home Assistant profile page.

2. Start the server:

# With flags
ha-mcp --ha-url http://homeassistant.local:8123 --ha-token your-token

# Or initialize config files first
ha-mcp init   # creates config.yaml and .env
ha-mcp        # start with config file

3. Connect your AI client. Example for Claude Desktop:

{
  "mcpServers": {
    "homeassistant": {
      "type": "http",
      "url": "http://localhost:8080",
      "headers": { "Authorization": "Bearer your-ha-access-token" }
    }
  }
}

See docs/configuration.md for Cline, opencode, and other client configurations.

Available Commands

Available Tools

41 tools organized by domain. Full reference at docs/tools.md.

Seven guidance topics are also available as MCP resources under `skill://ha-mcp/` URIs (format-selection, automation-patterns, template-resilience, helper-selection, dashboard-safety, entity-renaming, debugging-workflow).

Access Control

ha-mcp provides read-only mode, whitelist, and blacklist filtering at the tool and action level:

# config.yaml - read-only monitoring
server:
  read_only: true

# Or block specific operations
server:
  tool_filter:
    blacklist:
      - "call_service"
      - "manage_*:delete"

See docs/access-control.md for glob patterns, category filtering (`*:write`), and example scenarios.

Architecture

AI Client → HTTP/JSON-RPC → ha-mcp MCP Server
                                    │
               ┌────────────────────┴────────────────────┐
               │ WebSocket (primary)                      │ REST API
               │ - State queries, service calls           │ - Automation CRUD
               │ - Helper CRUD, Registry access           │ - Script/Scene CRUD
               └────────────────────┬────────────────────┘
                                    │
                             Home Assistant

See docs/architecture.md for project structure, build commands, and integration test setup.

Troubleshooting

See docs/troubleshooting.md for WebSocket connection issues, debug mode, and common error solutions.

Development

Prerequisites: Go 1.27+, golangci-lint v2, Docker (optional)

go build -o ha-mcp ./cmd/ha-mcp    # Build
go test ./...                       # Unit tests
golangci-lint run --timeout=5m ./...  # Lint

> If `golangci-lint` panics with "file requires newer Go version", your locally installed binary was built with an older Go toolchain than the one on `PATH`. Run `task lint:install` to rebuild it against your current toolchain.

See docs/architecture.md for integration test setup and docs/integration-tests.md for the full test suite documentation.

Contributing

See CONTRIBUTING.md for the full workflow (task commands, TDD

requirement, integration test setup, linter rules, and the docs checklist for

new tools). Please also read the Code of Conduct.

License

GPL-3.0 License - see LICENSE for details.

Acknowledgments

• Model Context Protocol specification
• Home Assistant WebSocket API
• coder/websocket - Pure Go WebSocket library