2026-06-16站内改写5 min readUpdated: 2026-06-16

The Unofficial and Home Assistant MCP Server

ha-mcp is a Model Context Protocol (MCP) server that enables AI assistants to interact with Home Assistant via natural language. It offers over 80 tools for device control, automation management, dashboard editing, debugging, and more, with multiple installation methods.

SourceHacker News AIAuthor: mooreds

Notifications You must be signed in to change notification settings

Fork 137

Star 3.4k

BranchesTags

Open more actions menu

Folders and files

NameName

Last commit message

Last commit date

Latest commit

History

1,678 Commits

.claude

.gemini

.github

custom_components/ha_mcp_tools

docs

homeassistant-addon-dev

homeassistant-addon-webhook-proxy

homeassistant-addon

packaging

rules

scripts

site

src/ha_mcp

templates

tests

.dockerignore

.env.example

.gitattributes

.gitignore

.gitmodules

.python-version

AGENTS.md

CHANGELOG.md

CLAUDE.md

CONTRIBUTING.md

Dockerfile

LICENSE

MANIFEST.in

PRIVACY.md

README.md

SECURITY.md

coverage.json

docker-compose.screenshot.yml

docker-compose.yml

fastmcp-http.json

fastmcp-sse.json

fastmcp-webclient.json

fastmcp.json

hacs.json

lefthook.yml

pyproject.toml

renovate.json

repository.yaml

server.json

sgconfig.yml

uv.lock

Repository files navigation

A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with Home Assistant.

Using natural language, control smart home devices, query states, execute services and manage your automations.

🚀 Get Started

Full guide to get you started with Claude Desktop (~10 min)

No paid subscription required. Click on your operating system:

Quick install (~5 min)

🍎 macOS

Go to claude.ai and sign in (or create a free account)

Open Terminal and run:

curl -LsSf https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install-macos.sh | sh

Download Claude Desktop (or restart: Claude menu → Quit)

Ask Claude: "Can you see my Home Assistant?"

You're now connected to the demo environment! Connect your own Home Assistant →

🐧 Linux

Anthropic doesn't ship Claude Desktop for Linux, so pick one path:

Claude Desktop — free, via the community build:

Install the community Claude Desktop for Linux build and sign in with a free claude.ai account

Open Terminal and run:

curl -LsSf https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install-linux.sh | sh

Restart Claude Desktop, then ask: "Can you see my Home Assistant?"

Claude Code — official CLI, requires a paid Claude plan:

Install Claude Code: curl -fsSL https://claude.ai/install.sh | bash

Configure ha-mcp, then run claude:

curl -LsSf https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install.sh | sh -s -- --claude-code

Start claude, run /mcp to confirm, then ask: "Can you see my Home Assistant?"

Full Linux guide →

🪟 Windows

Go to claude.ai and sign in (or create a free account)

Open Windows PowerShell (from Start menu) and run:

irm https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install-windows.ps1 | iex

Download Claude Desktop (or restart: File → Exit)

Ask Claude: "Can you see my Home Assistant?"

You're now connected to the demo environment! Connect your own Home Assistant →

🏠 Home Assistant OS (Add-on)

Add the repository to your Home Assistant instance:

Install "Home Assistant MCP Server" from the Add-on Store and wait for it to complete

Click Start, then open the Logs tab to find your unique MCP URL

Configure your AI client with that URL

No token or credential setup needed — the add-on connects to Home Assistant automatically.

Full add-on documentation →

🌐 Remote Access (Nabu Casa / Webhook Proxy)

Already have Nabu Casa or another reverse proxy pointing at your Home Assistant? The Webhook Proxy add-on routes MCP traffic through your existing setup — no separate tunnel or port forwarding needed.

Install the MCP Server add-on (see above) and the Webhook Proxy add-on from the same store

Start the webhook proxy and restart Home Assistant when prompted

Copy the webhook URL from the add-on logs:

MCP Server URL (remote): https://xxxxx.ui.nabu.casa/api/webhook/mcp_xxxxxxxx

Configure your AI client with that URL

For other remote access methods (Cloudflare Tunnel, custom reverse proxy), see the Setup Wizard.

Webhook proxy documentation →

🧙 Setup Wizard for 15+ clients

Claude Code, Gemini CLI, ChatGPT, Open WebUI, VSCode, Cursor, and more.

Having issues? Check the FAQ & Troubleshooting

💬 What Can You Do With It?

Just talk to Claude naturally. Here are some real examples:

You Say What Happens

"Create an automation that turns on the porch light at sunset" Creates the automation with proper triggers and actions

"Add a weather card to my dashboard" Updates your Lovelace dashboard with the new card

"The motion sensor automation isn't working, debug it" Analyzes execution traces, identifies the issue, suggests fixes

"Make my morning routine automation also turn on the coffee maker" Reads the existing automation, adds the new action, updates it

"Create a script that sets movie mode: dim lights, close blinds, turn on TV" Creates a reusable script with the sequence of actions

Spend less time configuring, more time enjoying your smart home.

✨ Features

Category Capabilities

🔍 Search Fuzzy entity search, deep config search, system overview

🏠 Control Any service, bulk device control, real-time states

🔧 Manage Automations, scripts, helpers, dashboards, areas, zones, groups, calendars, blueprints

📊 Monitor History, statistics, camera snapshots, automation traces, ZHA devices

💾 System Backup/restore, updates, add-ons, device registry

🔒 Safety Read Only Mode toggle, per-tool enable/disable, tool security policies (user approval), automatic edit backups

Complete Tool List (84 tools)

Category Tools

Add-ons ha_get_addon, ha_manage_addon

Areas & Floors ha_list_floors_areas, ha_remove_area_or_floor, ha_set_area_or_floor

Assist ha_manage_pipeline

Automations ha_config_get_automation, ha_config_remove_automation, ha_config_set_automation

Blueprints ha_get_blueprint, ha_import_blueprint

Calendar ha_config_get_calendar_events, ha_config_remove_calendar_event, ha_config_set_calendar_event

Camera ha_get_camera_image

Dashboard ha_get_dashboard_screenshot (beta)

Dashboards ha_config_delete_dashboard_resource, ha_config_delete_dashboard, ha_config_get_dashboard, ha_config_list_dashboard_resources, ha_config_set_dashboard_resource, ha_config_set_dashboard

Device Registry ha_get_device, ha_remove_device, ha_set_device

Energy ha_manage_energy_prefs

Entity Registry ha_get_entity_exposure, ha_get_entity, ha_remove_entity, ha_set_entity

Files ha_delete_file (beta), ha_list_files (beta), ha_read_file (beta), ha_write_file (beta)

Groups ha_config_list_groups, ha_config_remove_group, ha_config_set_group

HACS ha_get_hacs_info, ha_manage_hacs

Helper Entities ha_config_list_helpers, ha_config_set_helper, ha_remove_helpers_integrations

History & Statistics ha_get_automation_traces, ha_get_history, ha_get_logs

Integrations ha_get_integration, ha_get_system_health, ha_set_integration_enabled

Labels & Categories ha_config_get_category, ha_config_get_label, ha_config_remove_category, ha_config_remove_label, ha_config_set_category, ha_config_set_label

Scenes ha_config_get_scene, ha_config_remove_scene, ha_config_set_scene

Scripts ha_config_get_script, ha_config_remove_script, ha_config_set_script

Search & Discovery ha_get_overview, ha_get_state, ha_search

Service & Device Control ha_bulk_control, ha_call_event, ha_call_service, ha_get_operation_status, ha_list_services

System ha_config_set_yaml (beta), ha_get_updates, ha_manage_backup, ha_manage_custom_tool (beta), ha_manage_theme, ha_reload_core, ha_restart

Todo Lists ha_get_todo, ha_remove_todo_item, ha_set_todo_item

Utilities ha_eval_template, ha_install_mcp_tools (beta), ha_report_issue

Zones ha_get_zone, ha_remove_zone, ha_set_zone

🆚 ha-mcp vs. Home Assistant's built-in MCP Server

Home Assistant ships its own MCP Server integration. It is built on the Assist pipeline, so a connected MCP client can read and control the entities you have exposed to Assist and run the intents Assist understands — handy for voice-style control of already-exposed devices.

ha-mcp is a standalone server built for configuring, building, and debugging your smart home, not just controlling it. On top of device control, it adds capabilities the built-in integration does not have:

Capability Built-in MCP Server ha-mcp

Control exposed devices, query states Yes Yes

Entity scope Only entities exposed to Assist Everything in Home Assistant

Create / edit automations, scripts, scenes No Yes

Build & edit dashboards No Yes

Debug automations from traces, read history & logs No Yes

Manage helpers, areas, zones, labels, groups No Yes

Backups, add-ons, HACS, device & entity registry No Yes

Rule of thumb: Use the built-in integration for voice-style control of devices you have already exposed; use ha-mcp when you want an AI assistant that can also build and maintain your Home Assistant setup.

🔌 Custom Component (ha_mcp_tools) (beta)

Some tools require a companion custom component installed in Home Assistant. Standard HA APIs do not expose file system access or YAML config editing. This component provides both.

Tools that require the component:

Tool Description

ha_config_set_yaml (beta) Safely add, replace, or remove top-level YAML keys in configuration.yaml and package files (automatic backup, validation, and config check)

ha_list_files (beta) List files in allowed directories

ha_read_file (beta) Read files from allowed paths (config YAML, logs, and allowed directories)

ha_write_file (beta) Write files to allowed directories

ha_delete_file (beta) Delete files from allowed directories

All other tools work without the component. These five return an error with installation instructions if the component is missing.

These tools also require feature flags: HAMCP_ENABLE_FILESYSTEM_TOOLS=true (file tools) and ENABLE_YAML_CONFIG_EDITING=true (YAML editing). To enable the ha_install_mcp_tools installer tool, set HAMCP_ENABLE_CUSTOM_COMPONENT_INTEGRATION=true.

Install using HACS (recommended)

To add manually: open HACS > Integrations > three-dot menu > Custom repositories > add https://github.com/homeassistant-ai/ha-mcp (category: Integration) > Download.

After installing, restart Home Assistant. Then open Settings > Devices & Services > Add Integration and search for Home Assistant MCP Server Custom Component.

On Home Assistant OS / Supervised, the integration offers to add the add-on repository and install and start the Home Assistant MCP Server add-on for you — no need to add the add-on repository by hand. On Container / Core installs (no Supervisor) there is no add-on; run the server via Docker or pip and the integration just sets up the file/YAML services.

Install manually

Copy custom_components/ha_mcp_tools/ from this repository into your HA config/custom_components/ directory. Restart Home Assistant, then add the integration as described above.

🧠 Better Results with Agent Skills

This server gives your AI agent tools to control Home Assistant. For better configurations, pair it with Home Assistant Agent Skills — domain knowledge that teach

[truncated for AI cost control]