Build and fix Home Assistant automations and dashboards using natural language
When you ask to create an entryway light automation, the AI generates a rule with actual triggers and actions. This server reads and modifies Home Assistant configuration files, refines dashboards, and analyzes execution logs to fix broken automations. It provides an environment for designing and managing a smart home in natural language without memorizing complex YAML syntax.
v7.3.0 changes and recommended installation path
In the recent v7.3.0 release, the ha_config_set_yaml tool moved to beta status. The most recommended installation method is installing the HA-MCP integration via HACS or the Home Assistant Marketplace. This approach provides identical functionality across all installation types, including Home Assistant OS, Supervised, Container, and Core, without requiring separate apps or Docker containers. After installation, you enter an admin access token and select a client connection method, and the server runs directly inside Home Assistant. If you previously installed it using another method, it is advisable to switch to this integration to maintain a single instance.
Role distinction from the built-in MCP server
The MCP server built into Home Assistant is based on the Assist pipeline and focuses on querying and controlling the state of already exposed entities. In contrast, this repository specializes in creating and maintaining the structure of the smart home. It supports creating and editing automations, scripts, scenes, and dashboards, as well as managing helpers, areas, zones, labels, and groups. It also includes features for analyzing automation execution traces to diagnose issues and reading history and logs for debugging. Additionally, it covers backups, app management, HACS, and device and entity registry management, allowing it to be used as a tool for managing the entire system rather than just a simple control utility.
File system access and YAML editing tools
Privileged tools are provided for file system access and YAML configuration editing, which are difficult to reach via the standard API. Using ha_config_set_yaml, you can safely add, replace, or delete top-level keys in configuration.yaml, with automatic backup and validation performed during the process. Tools for listing, reading, writing, and deleting files are also included, allowing you to handle configuration files or logs directly. These features are disabled by default and must be enabled by turning on the beta feature flag. These tools become available only if you add the HA-MCP File & YAML Tools item via HACS or the Marketplace on Home Assistant 2026.8.0 or later.
Agent skills and tool search optimization
Agent Skills, which are domain knowledge that help AI agents understand Home Assistant best practices, are provided alongside the server. An MCP server alone may lack judgment regarding automation structure or helper selection, but these skills prioritize native components and guide safe refactoring workflows. Skills are provided as MCP resources via skill:// URIs, allowing clients that support resources to discover them automatically. For clients that only support tools, the ha_get_skill_guide tool allows reading skill guides, and this tool is fixed to be always available. Additionally, since the full tool catalog reaches approximately 87 items, small models or local LLMs may exceed their context window; setting ENABLE_TOOL_SEARCH=true enables a BM25 search-based tool discovery mode to fetch only the necessary tools.
Security and compatibility checks before use
This tool requires Home Assistant 2026.8.0 or later and is easiest to install in environments with access to HACS or the Marketplace. Because it uses an access token with admin privileges, it is safer to create a dedicated HA-MCP account and configure it to allow only local access if security is a concern. Enabling remote access generates a webhook URL, so if you do not want exposure to public networks, you should configure it for local network access only. The stdio transport method has a possibility of connection issues and is recommended only for demos or testing rather than actual use. File editing and YAML modification tools are in beta, so you must always check the backup status before modifying important configurations.
