GraphCanon
Home/Developer Tools/ha-mcp
ha-mcp logo

ha-mcp

homeassistant-ai/ha-mcp

Unofficial Home Assistant MCP Server for AI model integration

GitHub

GraphCanon updated 4w · GitHub synced 4w

4.1k stars172 forksLast push 4w Python MIT

Decision brief

ha-mcp provides unofficial support for integrating AI models, specifically those from frameworks like Claude, into Home Assistant via the Model Context Protocol (MCP).

Good fit when

  • When you need to integrate Claude AI models as an MCP component in your Home Assistant setup.
  • For users who wish to experiment with new and unofficial MCP-supported models not officially supported by Home Assistant.

Avoid when

  • If official support for AI model integration is required, since ha-mcp lacks this endorsement.
  • Not suitable if you prioritize stability over experimenting with cutting-edge functionalities.

Observed Jul 16, 2026 · Source: enrich:decision_facts

ha-mcp alternativesTrust report

Verify the decision

Maintenance and security

Full trust report
Maintenance
Very active (0d since push)
As of 4w
Provenance
Not a fork · Organization account
As of 4w
Security (OSV)
No MCP manifest
As of 1mo

Public GitHub metadata and optional OSV scans. Signals, not a guarantee. Trust methodology.

Install

pip install ha-mcp
PyPI

Similar tools

Same-category neighbours. No typed graph edges are catalogued for this tool yet.

Evidence and technical details

Sourced facts, taxonomy, compatibility claims, README excerpt, and machine-readable endpoints.

Overview

The repository provides unofficial support for integrating AI models into Home Assistant through the Model Context Protocol (MCP). It supports frameworks like Claude.

Capability facts

Deploy
Self-host

Source: dockerfile:Dockerfile · Jul 26, 2026

Docker
Dockerfile present

Source: dockerfile:Dockerfile · Jul 26, 2026

CLI
CLI entrypoint

Source: pyproject.toml:[project.scripts] · Jul 26, 2026

MCP server
No MCP server detected

Source: repo_scan · Jul 26, 2026

Languages
python

Source: github.language+pyproject.toml · Jul 26, 2026

Categories

Developer ToolsLLM Frameworks

Compatibility

Sourced claims from the README excerpt - not unsourced marketing copy.

stdio transportstdio

Source: README excerpt (regex_v1, Jul 26, 2026)

- **Local stdio (not recommended):** runs ha-mcp on your own machine over stdio. The one-comman
Source link
Works with ChatGPTChatGPT

Source: README excerpt (regex_v1, Jul 26, 2026)

**ChatGPT / Codex behind a firewall (OpenAI Tunnel).** ChatGPT connectors normally requir
Source link

Tags

aiclaudehacshome-assistanthome-automationllmmcpmodel-context-protocol

README

Other install methods

These run the server outside Home Assistant — useful for Container / Core installs (which can't run add-ons) 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, Google, 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.

🌐 Remote access (Nabu Casa / Webhook Proxy add-on / OpenAI Tunnel)

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 add-on (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 add-on routes MCP traffic through your existing setup — no separate tunnel or port forwarding needed.

  1. Install the MCP Server add-on (see above) and the Webhook Proxy add-on from the same store
  2. Start the webhook proxy and restart Home Assistant when prompted
  3. Copy the webhook URL from the add-on logs: 
    MCP Server URL (remote): https://xxxxx.ui.nabu.casa/api/webhook/mcp_xxxxxxxx
  4. Configure your AI client with that URL

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 →

Install

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

To add manually: open **H

For agents

This page has a .md twin and JSON over the API.

/tools/homeassistant-ai-ha-mcp.mdGET /api/graphcanon/tools/homeassistant-ai-ha-mcpGET /api/graphcanon/graph?tool=homeassistant-ai-ha-mcp

Was this helpful?

Anonymous feedback helps us improve pages and translations.