ha-mcp MCP工具

Other install methods

These run the server outside Home Assistant — useful for Container / Core installs (which can't run apps) or a separate host. The Setup Wizard generates the exact client-specific config for each.

• Docker (HTTP server): run ghcr.io/homeassistant-ai/ha-mcp in HTTP mode, pointed at your Home Assistant URL and a long-lived token, and connect your client to its secret URL. See the Setup Wizard for the full command and per-client config.
• PyPI / uvx (HTTP server): run the published ha-mcp package with uvx ha-mcp@latest (or pip) as a streamable-HTTP server the same way. Details in the Setup Wizard.
• Local stdio (not recommended): runs ha-mcp on your own machine over stdio. The one-command installers in the Demo server section below use this path; the Setup Wizard covers connecting it to your own Home Assistant.
• OIDC authentication: gate remote access behind an external identity provider (Authentik, Keycloak, Auth0, etc.) instead of a secret URL — all authenticated users share the server's Home Assistant credentials. See OIDC Mode.

⚠️ stdio has known transport issues. The stdio transport has connection problems that streamable HTTP does not (#1713). It is recommended only for demo/testing tinkering — for a real setup, use the custom component or an HTTP method above.

<details> <summary><b>🌐 Remote access (Nabu Casa / Webhook Proxy app / OpenAI Tunnel)</b></summary>

Using the HA-MCP custom component? You do not need the Webhook Proxy — the component has its own built-in webhook for remote access (see the Get Started quick start at the top). The proxy is for the app (it can also front another external server via its mcp_server_url option). The OpenAI Tunnel below is different: it applies to any install method when Home Assistant isn't publicly reachable at all (no Nabu Casa or reverse proxy).

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

1. Install the MCP Server app (see above) and the Webhook Proxy app from the same store 2. Start the webhook proxy and restart Home Assistant when prompted 3. Copy the webhook URL from the app logs:

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

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

ChatGPT / Codex behind a firewall (OpenAI Tunnel). ChatGPT connectors normally require a publicly reachable URL. If you can't (or don't want to) expose one, the community OpenAI Tunnel for HA-MCP integration by @norpol runs OpenAI's tunnel-client inside Home Assistant and connects your local MCP server URL to an OpenAI-hosted tunnel over an outbound-only connection — no port forwarding, reverse proxy, or public URL. Point it at your ha-mcp URL, then attach the ChatGPT connector to the same tunnel ID. See the FAQ entry and #1811.

Webhook proxy documentation →

</details>

🧙 Setup Wizard for 15+ clients

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

<p> <a href="https://homeassistant-ai.github.io/ha-mcp/setup/"><img src="https://img.shields.io/badge/Open_Setup_Wizard-4A90D9?style=for-the-badge" alt="Open Setup Wizard" height="40"></a> </p>

Having issues? Check the FAQ & Troubleshooting

---

Install

Install the HA-MCP File & YAML Tools entry from the same HA-MCP Custom Component:

To add manually: open HACS > Integrations > three-dot menu > Custom repositories > add https://github.com/homeassistant-ai/ha-mcp-integration (category: Integration) > Download. Or copy custom_components/ha_mcp_tools/ from this repository into your HA config/custom_components/ directory.

After installing, restart Home Assistant, then open Settings > Devices & Services > Add Integration, search for HA-MCP Custom Component, and add the HA-MCP File & YAML Tools entry.

To run the full ha-mcp server in-process through this same component, see the Get Started section at the top and the full in-process server documentation →.

---

🧪 Demo server (Windows / macOS / Linux)

Want to try ha-mcp before connecting your own Home Assistant? No paid subscription required. These one-command scripts set up a local stdio connection to a hosted demo environment so you can see it working in a few minutes. Each script's Connect your own Home Assistant link then shows how to point it at your instance.

<details> <summary><b>🍎 macOS</b></summary>

1. Go to claude.ai and sign in (or create a free account) 2. Open Terminal and run:

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

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

</details>

<details> <summary><b>🐧 Linux</b></summary>

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

Claude Desktop — free, via the community build:

1. Install the community Claude Desktop for Linux build and sign in with a free claude.ai account 2. Open Terminal and run:

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

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

1. Install Claude Code: curl -fsSL https://claude.ai/install.sh | bash 2. Configure ha-mcp, then run claude:

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

Full Linux guide →

</details>

<details> <summary><b>🪟 Windows</b></summary>

1. Go to claude.ai and sign in (or create a free account) 2. Open Windows PowerShell (from Start menu) and run:

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

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

</details>

🔌 Custom Component (ha_mcp_tools) — File & YAML Services

The HA-MCP Custom Component also powers a set of privileged tools that standard Home Assistant APIs can't provide: file system access and YAML config editing. (The same component runs the full server in-process — that's the recommended install in the Get Started section at the top.) Its File & YAML services entry (HA-MCP File & YAML Tools) enables the tools below.

Tools that require the component:

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

These tools also require beta feature flags. See Beta Features for how to enable them — including the ENABLE_BETA_FEATURES master flag, which must be on before the filesystem/YAML sub-flags take effect.

🆚 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:

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.

---