Nabu Casa

About

Automatic summary of the docs and configuration of homeassistant-ai/ha-mcp. Something wrong, or are you the maintainer and want your own text here? Get in touch

Supports

• Actively maintained Its author released or pushed a change in the last six months.

Setting it up

Add its app repository under Settings, Apps, then install and start it.

From the docs

Permissions

• Host networkUses the host's network directly instead of its own.
• Home Assistant APICan read and control Home Assistant.
• Supervisor APICan talk to the Supervisor, which manages apps and the system.

Configuration

• External URL (optional)Public base URL for remote access (e.g. https://example.customurl.com). It must point directly at Home Assistant — opening it in a browser should bring up your HA login page — and must not contain a port such as ":8123" (or any other port), or remote MCP clients won't be able to reach it. Leave blank to auto-detect Nabu Casa.
• MCP server URL (optional)Full URL of the MCP server to proxy to (e.g. http://192.168.1.100:9583/private_abc123). Leave blank to auto-discover from a running HA MCP addon.
• MCP server port (optional)Port the MCP addon listens on. Only used during auto-discovery. Default: 9583.
• Enable OAuth (Beta)Adds OAuth 2.1 authentication to the webhook URL. The same URL keeps working but now requires a successful OAuth flow before serving MCP requests. This is OFF by default and unchanged for anyone who leaves it off — the webhook then works exactly as before with no auth check. Two modes are available (see OAuth Mode below): - ha_auth (recommended, the default for a first-time enable): you sign in with your Home Assistant account. LEAVE the connector's OAuth fields BLANK — no Client ID or Client Secret. Works with any hostname/URL and needs NO Home Assistant restart to enable or disable. - legacy: the previous flow, where the addon generates a Client ID + Secret that you paste into the connector (see the OAuth Client ID / Secret options). Enabling legacy requires a full Home Assistant restart (a Repair with a restart button appears); disabling does not. Upgrades are safe: if you already used the legacy flow (you set a Client ID/Secret, or the addon stored one) the addon keeps you on legacy so your existing connector keeps working. Switching modes is an explicit action (set OAuth Mode) and requires deleting and re-adding your MCP connector.
• OAuth Mode (Beta)Which OAuth mode to use when Enable OAuth is on. Leave this UNSET unless you want to switch — the addon picks the right default automatically. - ha_auth: sign in with your Home Assistant account. Leave the connector's OAuth fields blank; works with any hostname/URL; no Home Assistant restart needed. This is the default for a first-time OAuth enable. - legacy: the previous client-id/secret flow (deprecated), for setups that still need it. When unset, upgrades stay safe: if you already used legacy OAuth (a configured or stored Client ID/Secret) the addon stays on legacy so nothing breaks; otherwise it defaults to ha_auth. Changing this and restarting switches modes — you must then delete and re-add your MCP connector.
• OAuth Client ID (legacy mode; auto-generated if blank)Legacy OAuth mode only (ignored in ha_auth mode). Client ID that the MCP client (e.g. Claude.ai) must present at the OAuth token endpoint. Leave blank to let the addon generate a value on first start (recommended); the generated value is persisted in /data/oauth_creds.json so it stays the same across restarts. If you set a value here it must be at least 16 characters long.
• OAuth Client Secret (legacy mode; auto-generated if blank)Legacy OAuth mode only (ignored in ha_auth mode). Client Secret that the MCP client (e.g. Claude.ai) must present at the OAuth token endpoint. Leave blank to let the addon generate a strong random value on first start (recommended). Treat the value like a password — anyone with it can complete the OAuth flow against your MCP server.
• Regenerate OAuth Credentials on Next Start (legacy mode)Legacy OAuth mode only (ignored in ha_auth mode). One-shot action: when you turn this on and restart the addon, the stored OAuth Client ID and Client Secret are wiped and fresh random values are generated. The new values are printed in the addon log and persisted across restarts. The addon attempts to flip this toggle back to off automatically after regenerating, so subsequent restarts don't keep regenerating. If that fails (older Supervisor versions), the addon log will tell you to manually flip this off. Use this when you suspect your OAuth credentials have leaked or simply want fresh ones. Remember to update your MCP client (e.g. Claude.ai) with the new values afterwards.
• Log inbound requests (Beta)Logs every request that reaches this webhook. The lines appear in this addon's own log (below) AND in the Home Assistant log (Settings -> System -> Logs, filter for "mcp_proxy"). The webhook is served inside Home Assistant rather than this addon, so the integration logs each request there and the addon mirrors those lines into this log. Each line shows the method, a masked webhook path, the source address, whether an Authorization header was present, and the upstream response status. Use this to confirm whether your MCP client (e.g. Claude.ai) is actually reaching the server: turn it on, restart the addon, try to connect from your client, and watch this log. If no inbound lines appear, the request never arrived — the problem is network reachability (public URL / DNS / TLS), not the addon. Restart the addon after changing this option. Leave off for normal operation.