What Is ha-mcp and How to Use It: An MCP Server for Building and Debugging Home Assistant

Asking an AI assistant to turn on a light works fine with Home Assistant's built in MCP integration. Ask it to create an automation, edit a script, or explain why a rule did not fire, and you hit a wall. ha-mcp is a standalone MCP server that hands configuration, construction, and debugging of a whole Home Assistant setup to the model. It exposes 87 tools, is written in Python, runs locally, and sends no telemetry.

What Is ha-mcp

ha-mcp is a standalone MCP server that lets Claude, ChatGPT, and other assistants do more than control exposed devices. It lets them configure, build, and debug an entire Home Assistant environment. The repository was created on 2025-09-14, still had commits on 2026-11-10, and has roughly 6,089 stars and 297 forks under MIT, with 87 tools exposed today. The built in Home Assistant MCP integration sits on the Assist pipeline, so it can only operate entities already exposed to Assist. It cannot create or edit automations, scripts, scenes, or dashboards, cannot read traces or history logs, and cannot manage helpers, areas, and zones. HA-MCP fills all of those gaps, and adds backup and configuration rollback along the way. The split between voice control and real configuration is the whole reason this server exists.

Features

• 87 tools. Search, control, management, monitoring, system, and security categories, including ha_search, ha_call_service, and ha_config_set_automation.
• Automation debugging. ha_get_automation_traces reads execution traces to show why a rule never fired.
• Safe YAML editing. A custom ha_mcp_tools component edits files with automatic backups, avoiding raw configuration changes.
• Tool discovery. Set ENABLE_TOOL_SEARCH=true for small models to collapse 87 tools into four entry points plus pinned tools, found through BM25 search.
• Domain knowledge built in. skill:// resources and the mandatory ha_get_skill_guide tool cover how HA is structured.
• Flexible deployment. Integration, add-on, Docker, uvx from PyPI, and local stdio are all supported.
• Privacy and safety. Local execution with no telemetry, plus a read only mode and per tool security policies.
• One click setup. Demo scripts and a Setup Wizard cover the first connection on every desktop platform.

For skill authoring see What Is anthropics/skills and How to Use It, and for another official set there is What Is google/skills and How to Use It.

How to Use

1. Check your HA version. The integration needs 2026.8.0 or newer, Marketplace needs 2026.11 or newer.
2. Choose a deployment. The HACS integration is easiest, or use an add-on or Docker image ghcr.io/homeassistant-ai/ha-mcp.
3. For an external HTTP service run uvx ha-mcp@latest. Local stdio is not recommended.
4. Use the Setup Wizard to generate an address, a webhook like https://<ha-domain>/api/webhook/<id> or a local URL like http://<ha-ip>:9584/private_<random>.
5. Add the MCP server in Claude Code, Gemini CLI, VSCode, or Cursor in read only mode.
6. Call ha_search for an entity and ha_call_service to control it before allowing writes.
7. Have the assistant build one automation, then read ha_get_automation_traces.

Small models can overflow context when loading 87 tools at once, so turn on ENABLE_TOOL_SEARCH.

Supported Platforms

One click demo scripts exist for Windows, macOS, and Linux, so run a demo before choosing a long term deployment. The integration runs in process, while Docker and uvx keep the server outside Home Assistant entirely.

Pricing

It is MIT licensed and runs locally, with no subscription, quota, or cloud account, and the maintainers explicitly ship no telemetry. The costs are the hardware running Home Assistant and whatever the model provider charges when you call an AI assistant. Neither involves the MCP server. A local small model cuts that further, provided tool search is enabled to save context. Docker images and the PyPI package are free too, and company network builds are unrestricted.

Use Cases

• Bulk automations. Describe conditions and actions in plain language and have the assistant generate several rules.
• Debugging. Read traces to find out why an automation stayed silent overnight.
• Dashboards and scenes. Create and edit interfaces, scripts, helpers, and area settings.
• Backups. Use ha_manage_backup for a rollback point before making changes.
• Small models. BM25 tool discovery keeps context use down to a handful of entry points.
• Multiple clients. One MCP service for Claude Code, Cursor, and ChatGPT at the same time.
• Safe trials. Read only mode answers whether a model understands your setup.

Confirm a backup exists before any write, since a bad YAML edit can stop HA from starting. Run read only mode for a few days in production, then open up tools one at a time.

How It Works

The homeassistant-ai organization maintains it, with an active community and a clear position. Use the built in integration for voice control, use ha-mcp to build and maintain HA. It does not replace the official integration, only adds a configuration and debugging layer, so the two coexist. Context optimization for small models, automatic backups on file edits, and per tool security policies all point at the same concern, letting an AI change real configuration without breaking the house. MIT licensing and local, telemetry free operation matter a lot in a smart home. The 87 tools sound overwhelming, but search based discovery reduces them to a few entry points in practice.

Conclusion

If switching lights is no longer enough and you want an AI to help build and maintain Home Assistant, ha-mcp hands over the permissions with a safety net. Learn the tools in read only mode using a demo script, then enable writes with a backup at every step. The slogan is fair. The built in integration handles voice control, this one handles construction and maintenance. Backups make that reversible.

Project https://github.com/homeassistant-ai/ha-mcp