ha-mcp

Model Context Protocol (MCP)サーバーで、AIアシスタントにHome Assistantへのアクセスを提供し、スマートホームの制御と自動化管理を可能にします。

ドキュメント

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: 42 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

Get a long-lived access token from your Home Assistant profile page.
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

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

Command	Description
`ha-mcp`	Start the MCP server
`ha-mcp init`	Create config.yaml and .env in current directory
`ha-mcp config`	Display effective configuration (tokens masked)
`ha-mcp --help`	Show help and available flags

Available Tools

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

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

Category	Count	Highlights
Entity	5	`query_entities` (history/stats/health), `get_state`, `analyze_entity`
Registry	10	`get_registry`, `manage_area/label/floor/zone/person/tag/entity/device`
Automation	1	`manage_automation` (CRUD, toggle, coverage, JSON Patch + semantic patch)
Helpers	2	`manage_helper` (41 types), `helper_action`
Scripts & Scenes	2	`manage_script`, `manage_scene` (CRUD + execute/activate + JSON Patch + semantic patch)
Analysis	4	`analyze_entity`, `get_entity_dependencies`, `analyze_target`, `find_references`
Services	2	`call_service`, `list_services` (response-type calls via `return_response`)
History/Logbook	2	`query_entities` modes, `get_logbook` (entries + correlation)
Dashboards/Media	4	`manage_dashboard` (JSON Patch + semantic patch), `browse_media`, `manage_camera`, `sign_media_path`
Calendars & Todos	2	`manage_calendar`, `manage_todo`
System/Admin	7	`get_system_info`, `validate_config`, `manage_update`, `manage_blueprint`
Logs	1	`manage_system_log` (list WARN/ERROR entries, clear ring buffer)
Statistics	1	`manage_statistics` (list, validate, clear recorder long-term statistics)
HACS	1	`manage_hacs` (list, download, install, custom repos)
Guidance	1	`get_skill` (action=list to discover skills, action=read to fetch content)

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