HA-MCP

Overview

HA-MCP is a standalone Model Context Protocol server for Home Assistant. It is designed for configuring, building, and debugging a smart home, not only controlling it, and works with Claude, ChatGPT, Cursor, Copilot, and 15+ AI clients. It provides 87 tools across search, control, management, monitoring, system, and safety categories.

Key Features

• 87 tools across search, control, management, monitoring, system, and safety categories.
• Natural-language device control, service calls, bulk operations, and real-time state tracking.
• Management of automations, scripts, helpers, dashboards, areas, zones, groups, calendars, and blueprints.
• Monitoring through history, statistics, camera snapshots, automation traces, and ZHA devices.
• System capabilities including backup and restore, updates, apps, device registry, and HACS management.
• Safety features such as Read Only Mode, per-tool enable/disable, tool security policies, and automatic edit backups.

Use Cases

• Create an automation that turns on the porch light at sunset.
• Add a weather card to a Lovelace dashboard.
• Debug a motion sensor automation by analyzing execution traces and suggesting fixes.
• Create a reusable movie-mode script that dims lights, closes blinds, and turns on the TV.

Getting Started

• Install the HA-MCP integration through HACS, or through Settings → Marketplace on Home Assistant 2026.11 or newer.
• Restart Home Assistant.
• Choose an administrator account: use a long-lived access token, or create a dedicated administrator account with local access only.
• Add the HA-MCP Server integration and choose remote access through Home Assistant and/or local network access.
• Copy the connect URL from the Configure screen and paste it into your AI client.

Deployment & Requirements

• The HA-MCP integration requires Home Assistant 2026.8.0 or newer.
• The in-process server works on Home Assistant OS, Supervised, Container, and Core with full feature parity.
• The app (add-on) is available on Home Assistant OS and Supervised installs.
• Docker, PyPI/uvx, and local stdio run the server outside Home Assistant and are useful for Container or Core installs or a separate host.
• Setup requires an administrator access token or a dedicated administrator account.

Before You Adopt

• License: MIT. Review its terms before using, modifying, or distributing the project.
• Run only one ha-mcp installation method; the in-process server replaces the app, Docker, and uvx/PyPI methods.
• Configure exactly one install method per client to avoid connection hangs.
• The stdio transport has known connection problems that streamable HTTP does not.
• OIDC authentication makes all authenticated users share the server's Home Assistant credentials.
• The File & YAML services entry is optional and only needed when opt-in file and YAML editing tools are enabled.