Home Assistant HA-MCP: Full Smart-Home Control for Claude, ChatGPT, and Cursor

The homeassistant-ai/ha-mcp repository ships a full-configuration MCP server that lets Claude, ChatGPT, Cursor and other clients write automations, edit dashboards, inspect traces and run backups in Home Assistant, rather than only reading or toggling entity states. As of November 9, 2026, the repo shows roughly 5,550 GitHub stars and more than 3,400 commits, with the in-process HA-MCP integration installed via HACS or the Home Assistant 2026.11 Marketplace positioned as the default path and Docker, add-on and uvx options for Container/Core setups. The server exposes 87 tools across search, control, configuration, monitoring and system categories, and its README warns users to run only one server instance per client because duplicate URLs are a known hang cause (issue #1713).

HA-MCP is Home Assistant's answer to a narrow problem: most MCP connectors only flip lights that Assist already exposes. The homeassistant-ai/ha-mcp https://github.com/homeassistant-ai/ha-mcp?ref=explainx repository ships a full-configuration MCP server so Claude, ChatGPT, Cursor, and other clients can write automations , edit dashboards , inspect traces , and run backups —not just read states. As of November 9, 2026, the repo shows roughly 5,550 GitHub stars and active development 3,400+ commits . The README positions the in-process HA-MCP integration HACS or Home Assistant 2026.11 Marketplace as the default install, with Docker, add-on, and uvx paths for Container/Core setups. Why builders care now Smart-home AI sat in two camps through 2025: 1. Voice assistants with rigid intents. 2. Cloud vendor MCP demos that only toggled a few entities. HA-MCP targets the third lane : treat Home Assistant like infrastructure your coding agent can refactor. That aligns with how explainx.ai readers already wire Google Home device control through MCP https://explainx.ai/blog/google-home-mcp-claude-chatgpt-2026 and how Meta Muse Gadgets SDK https://explainx.ai/blog/meta-muse-gadgets-sdk-home-link-2026 examples mention Home Assistant bridges. The difference is depth. Google's connector is consumer control. HA-MCP is DevOps for your house . What the server can do The GitHub README https://github.com/homeassistant-ai/ha-mcp?ref=explainx documents natural-language examples: | You say | HA-MCP action | |---|---| | Create an automation that turns on the porch light at sunset | Builds triggers and actions | | Add a weather card to my dashboard | Edits Lovelace | | Debug why a motion automation failed | Pulls execution traces | | Create a movie-mode script | Writes a reusable script | Behind those flows sit 87 tools grouped into search, control, configuration, monitoring, and system categories. Highlights include: - Automations and scripts: ha config get/set automation , script CRUD, blueprint management. - Dashboards: resource lists, layout edits, optional screenshot beta tool. - Diagnostics: history, statistics, logs, automation traces, camera snapshots. - Registry work: areas, zones, labels, device and entity registry edits. - Operations: backups, updates, HACS, app management, optional YAML beta tools. Optional file and YAML tools moved to beta in v7.3.0 and stay off unless you enable feature flags and add the File & YAML Tools integration entry. Install paths pick exactly one The README warns: run only one server instance per client . Duplicate URLs for example uvx stdio plus an add-on URL are a known hang cause 1713 https://github.com/homeassistant-ai/ha-mcp/issues/1713?ref=explainx . Recommended: in-process integration On Home Assistant 2026.8+ : 1. Install HA-MCP from HACS , or from Settings → Marketplace on 2026.11+ catalog entry, no custom repo . 2. Restart Home Assistant. 3. Create a dedicated administrator account safer than pasting your personal long-lived token . 4. Add integration HA-MCP Server , choose Remote webhook and/or Local network access, submit. 5. Copy the connect URL from the integration's Configure screen into your AI client. Remote clients use https://<your-domain /api/webhook/<id ; LAN clients may hit http://<ha-ip :9584/private <token . Add-on, Docker, and uvx Home Assistant OS/Supervised users can install the Home Assistant MCP Server app from the same GitHub org. Container/Core users run the published image or uvx ha-mcp@latest in HTTP mode with a long-lived token. The Setup Wizard https://homeassistant-ai.github.io/ha-mcp/?ref=explainx generates client-specific configs for 15+ clients , including Claude Code, Gemini CLI, ChatGPT, Open WebUI, VS Code, and Cursor. Demo scripts macOS, Linux, and Windows one-liner installers pull a hosted demo over stdio so you can test before pointing at your instance. Treat stdio as tinkering only; production setups should use streamable HTTP . HA-MCP vs built-in Home Assistant MCP Home Assistant ships its own MCP Server integration https://www.home-assistant.io/integrations/mcp server/?ref=explainx tied to Assist. The README comparison table is explicit: | Capability | Built-in MCP | HA-MCP | |---|---|---| | Control exposed devices | Yes | Yes | | Entity scope | Assist exposure only | Full instance | | Create/edit automations | No | Yes | | Build/edit dashboards | No | Yes | | Debug traces, logs | No | Yes | | Backups, HACS, registry | No | Yes | Rule of thumb: use built-in MCP for voice-style control of a curated subset. Use HA-MCP when an agent is your co-administrator . For protocol background, see What is MCP? https://explainx.ai/blog/what-is-mcp-model-context-protocol-guide and Pi's MCP Codemode reversal https://explainx.ai/blog/pi-adds-mcp-codemode-earendil-reversal-2026 on when HTTP MCP beats local CLIs. Client wiring notes - Claude Desktop / Claude.ai: paste the Configure URL; optional ha auth mode requires Home Assistant login instead of secret URLs. - ChatGPT: normally needs public HTTPS; use Nabu Casa webhook proxy or the community OpenAI Tunnel described in the README FAQ. - Cursor / VS Code: Setup Wizard snippets add the MCP entry to your config JSON. - Read-only exploration: toggle Read Only Mode before letting a model inspect production. The project site at homeassistant-ai.github.io/ha-mcp https://homeassistant-ai.github.io/ha-mcp/?ref=explainx hosts deeper docs than this news post. Security: treat it like root on your home HA-MCP is powerful because it uses administrator credentials . Misconfigured remote webhooks or leaked secret URLs are equivalent to handing someone your Home Assistant owner password . Mitigations built into the project: - Read Only Mode for audits. - Per-tool enable/disable and user-approval security policies . - Automatic edit backups before helper and automation changes with restore rules documented in the README . - Guidance to create a dedicated HA-MCP user , never your daily login. For agent harnesses that can call MCP at scale, pair operational discipline with an agent guardrail product. When an LLM can delete automations or open doors through scripts, use workflow review and tools like AgentBeam https://agentbeam.com/?ref=explainx where they fit your approval and blocking layer—especially if you connect the same MCP URL to autonomous coding agents. Camera pipelines deserve separate hardening. If you expose ha get camera image , remember lessons from Frigate NVR https://explainx.ai/blog/frigate-nvr-ai-camera-system-2026 deployments: segment VLANs, rotate tokens, and avoid shipping snapshots to cloud models you do not trust. Trending signal GitHub Trending listed ha-mcp with a modest daily star gain on November 9, 2026, but the repo already had thousands of stars before that bump. The real news is Marketplace placement on HA 2026.11 , which lowers install friction for mainstream Home Assistant users who do not live in GitHub. Compare with Vercel agent-desktop https://explainx.ai/blog/vercel-agent-desktop-accessibility-tree-computer-use-cli-2026 for desktop automation and Cloudflare's security-audit skill https://explainx.ai/blog/cloudflare-security-audit-skill-open-source-agent-vulnerability-hunting-2026 for codebase audits—the pattern is the same: official org repos shipping MCP surfaces agents can drive. How to evaluate before production 1. Start read-only on a snapshot instance or demo environment. 2. Script a harmless automation test light and verify trace output. 3. Enable destructive tools one category at a time dashboards before YAML beta . 4. Log every webhook URL and rotate if it leaks in a chat export. 5. Document rollback using HA-MCP backup tools plus native Home Assistant backups. Limitations - stdio transport remains discouraged; use HTTP. - Beta YAML/file tools can break configs; keep them off until you need them. - ChatGPT without tunnel/proxy still needs a public URL. - Built-in vs HA-MCP duplication confuses clients—do not enable both for the same assistant. Version and packaging timeline HA-MCP is not a weekend hack. The repository shows years of commits and a formal CHANGELOG with semver tags. A breaking note in v7.3.0 moved ha config set yaml to beta , reflecting how dangerous raw YAML edits are in production. The v9.0.0 setup flow October 28, 2026 and later added the explicit administrator account step in the integration UI. Home Assistant 2026.11 then folded HA-MCP into the default Marketplace catalog , which matters because most owners never configure custom HACS repos. That distribution shift—not a one-day star bump—is why the project reappeared on GitHub Trending in early November. If you still run the legacy homeassistant-ai/ha-mcp-integration fork, the README says it receives the same releases . Search HA-MCP in Marketplace regardless of display name quirks. Remote access patterns Three patterns dominate production: | Pattern | Best for | Notes from README | |---|---|---| | Nabu Casa webhook | Claude.ai, mobile clients | Webhook Proxy app shares URL via logs | | Reverse proxy / Cloudflare Tunnel | Self-hosted HTTPS | Setup Wizard templates | | OpenAI Tunnel | ChatGPT without public ports | Outbound-only; community integration | OIDC mode replaces secret URLs with an external IdP Authentik, Keycloak, Auth0 . Every authenticated user shares the server’s Home Assistant credentials—fine for households, risky for multi-tenant hosts. Local-only installs can leave remote access disabled so no webhook registers , while the LAN port and sidebar admin panel still work. That is the right default on VLAN-segmented labs. Tooling depth: why 87 tools matter Assist exposes intents ; HA-MCP exposes the configuration graph . Examples beyond the README’s marketing blurbs: - Automation traces ha get automation traces let an agent see why a motion sensor pipeline failed without you copying YAML into chat. - Dashboard screenshots beta help vision models verify Lovelace layout before you publish. - ZHA and Matter radios ha manage radio move configuration reads into the agent loop for Zigbee debugging—pairs well with hardware posts like OOMoo DIY vacuums https://explainx.ai/blog/oomwoo-open-source-diy-robot-vacuum-august-2026 when robots share the same coordinator. - HACS management means an agent can install integrations you approve—treat that as supply-chain risk and keep backups. The optional file/YAML beta tools are off by default. Enable them only on a staging instance cloned from production. Pairing HA-MCP with coding agents Cursor and Claude Code users often run two MCP servers : one for Git, one for home. Keep URLs separate and document which workspace uses which. The same caution applies when you combine HA-MCP with Vercel agent-desktop https://explainx.ai/blog/vercel-agent-desktop-accessibility-tree-computer-use-cli-2026 on a desktop automation host—two agents with full control planes on one machine multiply blast radius. A saner pattern: HA-MCP on a dedicated admin account with approval policies , Git MCP on developer machines, and read-only HA tools for demos. Governance and household consent Smart-home agents touch physical actuators : locks, garage doors, irrigation, scenes that imply someone is home. Document who can approve tool calls. If minors or guests share your network, segment IoT VLANs and disable risky services in HA-MCP’s tool policy UI. When cameras are in scope, align with Frigate NVR hardening https://explainx.ai/blog/frigate-nvr-ai-camera-system-2026 : never stream interior feeds to a cloud model without explicit household consent.