HA-MCP: Let Claude and ChatGPT manage Home Assistant
An MCP server that lets Claude and ChatGPT manage Home Assistant with 87 tools across four installation types.
GitHub homeassistant-ai/ha-mcp Updated 2026-11-10 Branch master Stars 6.0K Forks 293
Python Home Assistant MCP Claude ChatGPT HACS Home Assistant 2026.8+

🧭 Decision Guide

Try it if you

  • You run Home Assistant 2026.8+ and want to install the HA-MCP integration through HACS.
    The Get Started section requires Home Assistant 2026.8.0 or newer and recommends the HA-MCP integration.
  • You need Claude, ChatGPT, or Cursor to operate devices, automations, and scripts.
    The Setup Wizard lists Claude Code, ChatGPT, VSCode, and Cursor, while Features lists device control, automation, and script tools.
  • You need to connect an AI client through Remote access through Home Assistant or the Local network.
    Step 4 of Get Started lists Remote access through Home Assistant and Network access: Local network.

Skip it if you

  • Your Home Assistant version is older than 2026.8.0.
    Get Started explicitly states that the HA-MCP integration requires Home Assistant 2026.8.0 or newer.
  • You require ha_config_set_yaml to be stable rather than beta.
    The Breaking change (v7.3.0) notice says ha_config_set_yaml has been moved to beta.
  • You cannot accept credentials that work from anywhere if an administrator token leaks.
    Step 3 of Get Started says a long-lived access token works from anywhere if it leaks.

Requirements

  • The HA-MCP integration requires Home Assistant 2026.8.0 or newer.
  • You must restart Home Assistant and then add the HA-MCP Server integration.
  • You need an administrator long-lived access token, or a separate HA-MCP account with Administrator permission.
  • You must obtain the connect URL from the Configure page and paste it into the AI client.
  • Remote connections use Remote access through Home Assistant; same-network connections can use Network access: Local network.

Watch out

  • HA-MCP starts with both Remote access and Network access disabled.
    Step 4 of Get Started states: Both start disabled.
  • Do not use your own login for the second account option; the README requires a separate HA-MCP account.
    Step 3 of Get Started recommends a separate account and says: Never use your own login for the second option.
  • ha_config_set_yaml entered beta because of the v7.3.0 breaking change.
    The README's Breaking change (v7.3.0) notice states this change.
  • When restoring a Helper, entity ID collisions are refused before creation, and other entity or device registry settings are not restored.
    The Template helper edit backups section says collisions are refused and other entity/device registry settings are not restored.

Not stated in the README

  • The provided README excerpt does not specify performance, latency, or concurrency limits for the 87 tools.
  • The provided README excerpt does not provide a per-client compatibility matrix for Claude, ChatGPT, or Gemini CLI versions.
  • The provided README excerpt does not describe upgrade migration or rollback procedures for the HA-MCP integration.
  • The provided README excerpt does not explain the exact secret-rotation process for Remote access using Secret URL.
  • The provided README excerpt does not describe the change scope of Dev Build 9.2.0.dev3439 compared with stable releases.

💡 Deep Analysis

6
Yes I run Home Assistant 2026.8–2026.10 in a Container, install components through HACS, and want Claude Code to query entities and modify automations and scripts. Is HA-MCP suitable for this setup?
For: An automation maintainer running Home Assistant 2026.8–2026.10 Container, managing components through HACS, and primarily using Claude Code

Yes, because the integration explicitly supports Container installations, HACS, and Claude Code configuration.

  • The README requires Home Assistant 2026.8.0 or newer, so Home Assistant 2026.8–2026.10 meets the stated minimum.
  • The HA-MCP integration runs in-process and the README lists Home Assistant OS, Supervised, Container, and Core with full feature parity.
  • The feature list includes ha_config_set_automation, ha_config_set_script, ha_get_state, and ha_search, covering discovery, inspection, and configuration changes.
  • The setup-wizard section explicitly lists Claude Code and says that the integration must be added as an HA-MCP Server after installation.

HACS download alone does not finish configuration; the server still has to be added under “Settings → Devices & services.”

  • Get Started: requires Home Assistant 2026.8.0 or newer
  • Get Started: works on every Home Assistant installation type — Home Assistant OS, Supervised, Container, and Core
  • Setup Wizard for 15+ clients: Claude Code
  • Features / Complete Tool List: `ha_config_set_automation`, `ha_config_set_script`, `ha_get_state`, `ha_search`
Not stated in the README:The provided README excerpt does not specify whether Claude Code should use local networking, a webhook, or another connection mode in a Container deployment.;It does not specify the exact authentication UI or token-storage behavior for this Home Assistant and HACS version combination.
It depends I need AI to modify automations, scripts, dashboards, and YAML, and recover after failures. I can accept beta status for YAML and dashboard screenshots, but is HA-MCP suitable for this kind of configuration management?
For: An advanced Home Assistant user who maintains automations, scripts, dashboards, and YAML and cares about recovery boundaries after failed configuration changes

It depends: structured configuration management is a good fit, but beta YAML features and recovery boundaries mean this is not a complete configuration-versioning system.

  • The tool list directly provides read/write tools for automations, scripts, dashboards, and helper entities, including ha_config_set_automation, ha_config_set_script, and ha_config_set_dashboard.
  • The README marks ha_config_get_yaml, ha_config_set_yaml, and ha_get_dashboard_screenshot as beta; the v7.3.0 breaking-change note specifically moved ha_config_set_yaml to beta.
  • The Safety section says edits receive automatic backups; helper restoration checks config-entry identity, entity-ID collisions, and persisted options.
  • However, the README also states that device/entity registry settings are not restored, older snapshots cannot preserve renamed entity IDs, and collisions or verification failures may leave a newly created object for inspection.

It is therefore suitable for AI-assisted changes, but should not be treated as a transactional rollback system covering all Home Assistant state.

  • Breaking change (v7.3.0): `ha_config_set_yaml` has been moved to beta
  • Complete Tool List: `ha_config_set_automation`, `ha_config_set_script`, `ha_config_set_dashboard`, `ha_config_get_yaml`, `ha_config_set_yaml`
  • Features / Safety: automatic edit backups
  • Features: restoring an existing helper requires a fresh safety backup and verifies persisted options
  • Features: Other entity/device registry settings are not restored; older snapshots cannot preserve renamed entity IDs
Not stated in the README:The README excerpt does not specify where automatic backups are stored, how many are retained, or whether every configuration file is covered.;It does not describe restoration ordering or complete dependency handling across dashboard resources, YAML files, and non-helper entity configuration.
It depends I manage locks, alarms, and cameras, and the ChatGPT connection requires Home Assistant administrator privileges. I want read-only access first and approval for high-risk actions. Is HA-MCP suitable?
For: A Home Assistant user managing locks, alarms, and cameras who is considering giving ChatGPT an administrator token but does not want AI to execute high-risk controls directly

It depends: the available safety controls match your requirements, but administrator-token exposure and high-risk devices cannot rely on project safeguards alone.

  • The README’s Safety section includes Read Only Mode, per-tool enable/disable, tool security policies with user approval, and automatic edit backups.
  • Read-oriented tools include ha_get_state, ha_get_history, and ha_get_logs; cameras also have ha_get_camera_image, allowing an initial diagnostic-only tool set.
  • The project insight warns that a leaked administrator token can be used from anywhere, and that natural-language misinterpretation can affect locks, alarms, heating, or cameras.
  • ha_call_service, ha_bulk_control, and ha_restart have direct device or system impact, so read-only mode should not be treated as proof that every client behaves identically.

If your policy requires independent hardware-level safety isolation, HA-MCP alone does not satisfy it.

  • Features: Safety — Read Only Mode toggle, per-tool enable/disable, tool security policies (user approval), automatic edit backups
  • Complete Tool List: `ha_get_state`, `ha_get_history`, `ha_get_logs`, `ha_get_camera_image`
  • Complete Tool List: `ha_call_service`, `ha_bulk_control`, `ha_restart`
  • Project insight, user_experience.common_pitfalls: a leaked administrator token can be used from anywhere
  • Project insight, usage_limitations: it cannot replace human confirmation for locks, alarms, heating, electrical equipment, or privacy cameras
Not stated in the README:The README excerpt does not state whether Read Only Mode automatically blocks every write, restart, and service-call tool.;It does not state whether the ChatGPT client fully supports the project’s user-approval policies or how approval prompts are presented.
Yes I use ZHA or Z-Wave and need device states, history, automation traces, system logs, and radio configuration parameters during troubleshooting. Can HA-MCP reduce switching between Home Assistant pages?
For: A Home Assistant operations user using ZHA or Z-Wave who needs history and automation traces to investigate intermittent failures

Yes, it is suitable: the tools cover the main diagnostic sources you listed, although they do not repair device, radio-network, or integration faults themselves.

  • ha_get_state and ha_get_overview in Search & Discovery can establish the target entity and system context first.
  • ha_get_history, ha_get_automation_traces, and ha_get_logs cover history, automation traces, and system logs respectively.
  • The README’s Monitor table explicitly lists history, statistics, automation traces, and ZHA devices; the tool list also includes ha_manage_radio.
  • For Z-Wave, the README says ha_manage_radio supports get_config_params and get_config_param; reads use the Z-Wave JS cache by default, while a single full root parameter can request a device read.

It can consolidate diagnostic context, but the project insight states that offline devices, unstable wireless networks, and integration-driver defects are not automatically fixed by HA-MCP.

  • Features: Monitor — History, statistics, camera snapshots, automation traces, ZHA devices
  • Complete Tool List: `ha_get_state`, `ha_get_overview`, `ha_get_history`, `ha_get_automation_traces`, `ha_get_logs`, `ha_manage_radio`
  • README Z-Wave section: `get_config_params`, `get_config_param`; reads use the Z-Wave JS cache by default
  • Project insight, usage_limitations: it does not automatically solve offline devices, integration-driver defects, or unstable wireless networks
Not stated in the README:The README excerpt does not specify which diagnostic fields are available for ZHA or whether ZHA parameters can be modified.;It does not specify time-range or volume limits for history and log queries, or their concrete impact on Home Assistant host load.
It depends I already use Home Assistant 2026.11 and want to install HA-MCP from Marketplace, then let remote ChatGPT query states and control devices without maintaining another proxy. Is this suitable?
For: A home-automation user on Home Assistant 2026.11 who wants to install HA-MCP from Marketplace and access the home instance remotely from ChatGPT

It depends: the installation path is a good fit, but remote authentication and exposure boundaries determine whether the overall design is appropriate.

  • The README says Home Assistant 2026.11+ can install HA-MCP from Settings → Marketplace; it is in the default catalog, so GitHub access or a custom repository is not required.
  • The integration runs in-process and asks for an administrator access token and client connection method, so a separate HA-MCP proxy is not required.
  • The tool list includes ha_get_state, ha_call_service, and ha_bulk_control, which cover ChatGPT state queries and device control.
  • The project insight describes both local-network and remote connections through Home Assistant/Nabu Casa or a reverse proxy, while noting that remote access, webhooks, and reverse proxies have different security boundaries.

If you cannot clearly restrict the remote URL, authentication method, and credential storage, exposing control tools is not a suitable deployment choice.

  • Get Started: On Home Assistant 2026.11 or newer, open Settings → Marketplace
  • Get Started: HA-MCP is in the default catalog
  • Get Started: setup asks for an administrator access token and how clients may connect
  • Complete Tool List: `ha_get_state`, `ha_call_service`, `ha_bulk_control`
  • Project insight, user_experience.common_pitfalls: remote connections, reverse proxies, webhooks, and local-network connections have different security boundaries
Not stated in the README:The README excerpt does not provide the complete configuration steps for remote ChatGPT connectivity.;It does not state whether a remote URL requires additional authentication, how tokens are rotated, or how the client stores administrator credentials.
It depends I use a smaller local model such as Ollama and do not want it to choose incorrectly among 87 tools. If my main tasks are entity search, state reads, and history queries, is HA-MCP suitable?
For: A Home Assistant user running a smaller local model such as Ollama who needs reliable entity discovery and state queries across 87 MCP tools

It depends: read-only tasks are a good fit, but a smaller model needs tool discovery or a reduced tool catalog.

  • The README lists 87 tools spanning search, device control, configuration, and system administration; that breadth increases selection complexity for a local model with limited tool-calling ability.
  • Search & Discovery provides ha_search, ha_get_overview, and ha_get_state, allowing the model to locate an entity before reading its state.
  • History & Statistics includes ha_get_history, covering historical queries; the project insight also identifies search-based discovery as a supported approach.
  • The README contents explicitly include “Smaller or local LLMs (Ollama, etc.)” and “Enable search-based discovery,” showing that this deployment is addressed, although the supplied excerpt omits the exact activation steps and defaults.

This is therefore not a “small model works reliably without adaptation” setup; it is a setup with a relevant discovery path.

  • Complete Tool List (87 tools)
  • Search & Discovery: `ha_search`, `ha_get_overview`, `ha_get_state`
  • History & Statistics: `ha_get_history`
  • README contents: Smaller or local LLMs (Ollama, etc.); Enable search-based discovery
  • Project insight, solution_analysis: search and discovery are provided as a distinct capability
Not stated in the README:The supplied README does not specify which Ollama models are supported, the minimum context window, or the required tool-calling format.;It does not state whether search mode is enabled by default or how the tool catalog is configured per connection URL.

✨ Highlights

  • 87 tools cover Home Assistant control and configuration
  • The HA-MCP integration supports four installation types
  • Works with Claude, ChatGPT, and 15+ clients
  • The project has 5,975 stars but its latest version is still a Dev Build

🔧 Engineering

  • Control devices and services with ha_call_service and ha_bulk_control
  • Manage automations and scripts with ha_config_set_automation
  • Inspect history, statistics, and automation traces with ha_get_history
  • Read Only Mode and tool security policies support approval control

⚠️ Risks

  • A leaked administrator token works from anywhere
  • Remote access and Network access are disabled by default
  • ha_config_set_yaml moved to beta in v7.3.0
  • Tools such as ha_restart and ha_manage_backup can change system state

👥 For who?

  • Home automation users running Home Assistant 2026.8+
  • Developers who want Claude or ChatGPT to operate HA
  • Users running HA OS, Supervised, Container, or Core
  • Teams integrating Claude Code, Gemini CLI, or Cursor