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

• 38 Specialized Tools: Entity queries, automation CRUD, helper management, scripts, scenes, devices, areas, labels, floors, zones, persons, tags, traces, blueprints, updates, todos, calendars, cameras, dashboards, 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, ~10 intent-based tools) and the community homeassistant-ai/ha-mcp (Python/FastMCP, 95+ tools).

Choose ha-mcp if you need:

• Full automation/script/scene/helper lifecycle management (create, edit, delete)
• Advanced analysis (dependencies, cross-references, automation coverage)
• System administration (registry queries, config validation, logbook, history)
• Media management (browser, camera streams), HACS, and dashboard access
• Reliable LLM tool selection — 38 consolidated tools reduce selection errors compared to 95+ fine-grained alternatives

Choose the official integration if you need entity-level security or no external infrastructure.

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.26 or later.

git clone https://github.com/zorak1103/ha-mcp.git
cd ha-mcp
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

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

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

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 (26 types), helper_action
Scripts & Scenes	2	manage_script, manage_scene (CRUD + execute/activate + JSON Patch + semantic patch)
Analysis	3	analyze_entity, get_entity_dependencies, analyze_target
Services	2	call_service, list_services
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
HACS	1	manage_hacs (list, download, install, custom repos)

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.26+, golangci-lint v2, Docker (optional)

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

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

Contributing

1. Fork the repository and create a feature branch
2. Make your changes with tests
3. Ensure CI passes:

   golangci-lint run ./...
   go test -race ./...
   

4. Open a Pull Request

Pull Request Guidelines

• Ensure CI checks pass (lint, test, security scans)
• Update documentation if needed
• Add tests for new functionality
• Keep commits focused and atomic

License

GPL-3.0 License - see LICENSE for details.

Acknowledgments

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