From b75d4b39160f72e6d5b225a086a54d690e009d1d Mon Sep 17 00:00:00 2001 From: Allen Porter Date: Sun, 3 May 2026 15:37:51 +0000 Subject: [PATCH 1/5] Clarify MCP Server setup instructions for local and remote clients Co-authored-by: Copilot --- source/_integrations/mcp_server.markdown | 139 ++++++++++++++++------- 1 file changed, 100 insertions(+), 39 deletions(-) diff --git a/source/_integrations/mcp_server.markdown b/source/_integrations/mcp_server.markdown index 3482532fc6b8..59617bc08339 100644 --- a/source/_integrations/mcp_server.markdown +++ b/source/_integrations/mcp_server.markdown @@ -77,10 +77,10 @@ Clients that support OAuth can use this to allow you to give the client access to your Home Assistant MCP server. Home Assistant has adopted [IndieAuth](https://indieauth.spec.indieweb.org/) and does not require you to pre-define -an OAuth Client ID. Instead, the Client ID is the base of the redirect URL. +an OAuth Client ID. Instead, the Client ID is the base URL of the client application making the request. -- *Client ID*: If your redirect-uri is `https://www.example.com/mcp/redirect`, your client ID should be `https://www.example.com`. -- *Client Secret*: This is not used by Home Assistant and can be ignored or set to any value. +- *Client ID*: This is the base URL of the LLM application configuring the connector (for example, `https://claude.ai` for Claude, or `https://chatgpt.com` for ChatGPT). It should **not** be your Home Assistant server's URL. +- *Client Secret*: This is not used by Home Assistant. If the client strictly requires a value, you can put any random text or leave it blank. #### Long-Lived Access Tokens @@ -97,24 +97,76 @@ For more information about Authentication in Home Assistant, refer to the [Authe ### Example: Claude for Desktop -Claude for Desktop now supports remote MCP servers, making it extremely easy to connect to your -Home Assistant instance: +Claude for Desktop can connect to Home Assistant using either a cloud-based remote connector or a local MCP proxy server. + +**Option 1: Remote connector (requires public Home Assistant URL)** + +When using a remote custom connector in Claude for Desktop, the connection is brokered through Anthropic's cloud infrastructure. This means your Home Assistant instance must be publicly accessible from the internet. 1. Download [Claude for Desktop](https://claude.ai/download) and log in. -2. Click your profile name, select **Settings**, and go to **Connectors**. -3. Click **Add Custom Connector**. +2. Select your profile name, select **Settings**, and go to **Connectors**. +3. Select **Add Custom Connector**. 4. Enter the following details: - **Name**: "Home Assistant" (or any more descriptive name you prefer) - - **Remote MCP Server URL**: `https:///api/mcp` + - **Remote MCP Server URL**: `https:///api/mcp` - Under advanced settings: - **OAuth Client ID**: `https://claude.ai` - **OAuth Client Secret**: Leave this blank -5. Click **OK**. Now click **Connect** next to the entry created with the name you provided above. +5. Select **OK**. Now select **Connect** next to the entry created with the name you provided above. 6. Log in to your Home Assistant instance and allow the redirect back to Claude Desktop. 7. You can now enable tools from Home Assistant when chatting with Claude, allowing you to control Home Assistant in a similar way to how you control it through the Voice Assistant. Claude will ask you for permission before calling any tools. ![Screenshot of Claude for Desktop adding an item to a Home Assistant To-do list](/images/integrations/mcp_server/claude-todo-list-control.png) +**Option 2: Local MCP proxy server (for internal/local Home Assistant URLs)** + +If your Home Assistant instance is only accessible on your local network (for example, `http://homeassistant.local:8123` or `http://192.168.1.10:8123`) or behind a VPN, you can use a local MCP proxy. This allows Claude Desktop to connect directly from your computer without routing through Anthropic's cloud. + +1. Make sure you have a [Long-lived access token](#long-lived-access-tokens) from your Home Assistant account. +2. Install `mcp-proxy` following the instructions in the [README](https://github.com/sparfenyuk/mcp-proxy). For example: `uv tool install git+https://github.com/sparfenyuk/mcp-proxy`. +3. Locate your Claude Desktop configuration file (for example, `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS or `%APPDATA%\Claude\claude_desktop_config.json` on Windows). +4. Add the following to your `mcpServers` configuration: + + ```json + { + "mcpServers": { + "Home Assistant": { + "command": "mcp-proxy", + "args": [ + "--transport=streamablehttp", + "--stateless", + "http://:8123/api/mcp" + ], + "env": { + "API_ACCESS_TOKEN": "" + } + } + } + } + ``` +5. Restart Claude for Desktop to connect. + +### Example: ChatGPT + +ChatGPT supports connecting to remote Model Context Protocol servers for Plus, Pro, Business, and Enterprise/Edu users. ChatGPT currently only supports remote connections, which means your Home Assistant instance must be publicly accessible from the internet. + +1. Log in to [ChatGPT](https://chatgpt.com). Ensure developer mode is enabled for your account (this can be toggled in **Settings** > **Apps** > **Advanced Settings**). +2. Navigate to **Workspace settings** (or user settings), select **Apps**, and select **Create**. +3. Enter the following details: + - **Name**: "Home Assistant" (or any name you prefer). + - **MCP Server URL**: `https:///api/mcp` + - Select **OAuth** for the authentication mechanism. ChatGPT will attempt to auto discover OAuth settings. If this does not work you will need to manually enter the settings under **Advanced OAuth Settings** > **User defined oauth client**: + - Under **Client registration**: + - **OAuth Client ID**: `https://chatgpt.com` + - **OAuth Client Secret**: Enter any random text (it is not used by Home Assistant, but the ChatGPT configuration form may require a value). + - **Token endpoint auth method**: `client_secret_post` + - Under **OAuth endpoints**: + - **Auth Url**: `https:///auth/authorize` + - **Token url**: `https:///auth/token` + - **Authorization server base**: `https://` +4. Select **Create**. Once created, the app will appear in your **Enabled Apps**. +5. Begin a new chat in ChatGPT, open the apps menu, and select your newly created Home Assistant app. ChatGPT will prompt you to authenticate, which will redirect you to Home Assistant to log in and authorize the connection. + ### Example: Claude Code Claude Code supports remote MCP servers, making it easy to connect to your Home Assistant instance: @@ -132,7 +184,7 @@ Claude Code supports remote MCP servers, making it easy to connect to your Home } }' --client-secret ``` - The name "HA", the URL "https://", and the callback port "12345" are examples; adjust them to match your setup. + The name `"HA"`, the URL `"https://"`, and the callback port `"12345"` are examples; adjust them to match your setup. *(Note: `clientId: "http://localhost:12345"` is correct for the Claude Code CLI's internal local callback server. Do not change this to your Home Assistant URL.)* 3. Start `claude` and type `/mcp`. Navigate to your MCP listing (for example, **HA**) and press Enter. Select **Authenticate** to open a web browser to your Home Assistant login page. 4. After you authenticate to your Home Assistant server, Home Assistant will tell you that you can close the web browser. @@ -144,24 +196,25 @@ Claude Code supports remote MCP servers, making it easy to connect to your Home 2. Install `mcp-proxy` following the instructions in the [README](https://github.com/sparfenyuk/mcp-proxy). For example, `uv tool install git+https://github.com/sparfenyuk/mcp-proxy`. 3. Open the main Cursor Settings and select **MCP**. -4. Click **Add new global MCP server** and add the Home Assistant server configuration: +4. Select **Add new global MCP server** and add the Home Assistant server configuration: + ```json - { - "mcpServers": { - "Home Assistant": { - "command": "mcp-proxy", - "args": [ - "--transport=streamablehttp", - "--stateless", - "http://localhost:8123/api/mcp" - ], - "env": { - "API_ACCESS_TOKEN": "" - } - } - } - } - ``` + { + "mcpServers": { + "Home Assistant": { + "command": "mcp-proxy", + "args": [ + "--transport=streamablehttp", + "--stateless", + "http://:8123/api/mcp" + ], + "env": { + "API_ACCESS_TOKEN": "" + } + } + } + } + ``` 5. Save your `mcp.json` file. You can also find this file in the `$HOME/.cursor/mcp.json` directory. 6. Restart Cursor and return to the MCP settings. You should see the Home Assistant server in the list. The indicator should be green. 7. In chat agent mode (Ctrl+I), ask it to control your home and the tool should be used. @@ -205,18 +258,16 @@ The [MCP Prompts](https://modelcontextprotocol.io/docs/concepts/prompts) provide inform LLMs how to call the tools. The tools used by the configured LLM API are exposed. -## Known Limitations +## Known limitations The Home Assistant Model Context Protocol integration currently only supports a subset of MCP features: -| Feature | Supported by Home Assistant | -| ------- | --------- | -| Prompts | ✅ | -| Tools | ✅ | -| Resources | ❌ | -| Sampling | ❌ | -| Notifications | ❌ | +- **Prompts**: Supported +- **Tools**: Supported +- **Resources**: Not supported +- **Sampling**: Not supported +- **Notifications**: Not supported ## Troubleshooting @@ -254,17 +305,27 @@ or the MCP server in Home Assistant is not configured. To understand the root cause, first check debug logs on the client. For example in Claude for Desktop: -1. Visit **Settings...**. +1. Select **Settings...**. 2. Select **Developer**. -3. Select the `Home Assistant` MCP server. +3. Select the **Home Assistant** MCP server. 4. Select **Open Logs Folder**. 5. View `mcp-server-Home Assistant.log`. These are known problems and their resolution: - - `Client error '404 Not Found' for url 'http://localhost:8123/api/mcp'`: + - `Client error '404 Not Found' for url 'http://:8123/api/mcp'`: this means the MCP Server integration is not configured in Home Assistant. - - `Client error '401 Unauthorized' for url 'http://localhost:8123/api/mcp'`: + - `Client error '401 Unauthorized' for url 'http://:8123/api/mcp'`: this means that the long live access token is not correct. ... +### Repeated OAuth failures + +#### Symptom: Unable to access Home Assistant after several failed login attempts + +If you accidentally enter incorrect credentials or configuration details multiple times during the OAuth setup flow, Home Assistant might temporarily block your IP address for security. + +##### Resolution + +Check your `ip_bans.yaml` file in the Home Assistant configuration directory. If your computer's IP address or the client's IP is listed there, remove it and restart Home Assistant, then try authenticating again. + ## Removing the integration This integration can be removed by following these steps: From 91b3ca4b53cc7db162728e873f98f2aa8d31c373 Mon Sep 17 00:00:00 2001 From: Allen Porter Date: Sun, 3 May 2026 10:08:28 -0700 Subject: [PATCH 2/5] Apply suggestions from code review Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- source/_integrations/mcp_server.markdown | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/source/_integrations/mcp_server.markdown b/source/_integrations/mcp_server.markdown index 59617bc08339..3e274212c293 100644 --- a/source/_integrations/mcp_server.markdown +++ b/source/_integrations/mcp_server.markdown @@ -313,18 +313,20 @@ To understand the root cause, first check debug logs on the client. For example - `Client error '404 Not Found' for url 'http://:8123/api/mcp'`: this means the MCP Server integration is not configured in Home Assistant. - `Client error '401 Unauthorized' for url 'http://:8123/api/mcp'`: - this means that the long live access token is not correct. + this means that the long-lived access token is not correct. ... ### Repeated OAuth failures #### Symptom: Unable to access Home Assistant after several failed login attempts -If you accidentally enter incorrect credentials or configuration details multiple times during the OAuth setup flow, Home Assistant might temporarily block your IP address for security. +If authentication keeps failing during the OAuth setup flow, the most likely cause is that one or more OAuth details are incorrect, like the client ID, client secret, or Home Assistant URL. ##### Resolution -Check your `ip_bans.yaml` file in the Home Assistant configuration directory. If your computer's IP address or the client's IP is listed there, remove it and restart Home Assistant, then try authenticating again. +Review the OAuth configuration in your client and enter the details again. Make sure the client ID, client secret, and Home Assistant URL exactly match the values you configured for the MCP server in Home Assistant. + +If you have explicitly enabled IP bans in Home Assistant and repeated failed sign-in attempts caused a ban, check the `ip_bans.yaml` file in your Home Assistant configuration directory. If your computer's IP address or the client's IP address is listed there, remove it, restart Home Assistant, and then try authenticating again. ## Removing the integration From be10fc9aec02f9935378751cf97a692d843b9d8b Mon Sep 17 00:00:00 2001 From: c0ffeeca7 <38767475+c0ffeeca7@users.noreply.github.com> Date: Mon, 4 May 2026 08:32:38 +0200 Subject: [PATCH 3/5] Apply suggestions from code review Co-authored-by: c0ffeeca7 <38767475+c0ffeeca7@users.noreply.github.com> --- source/_integrations/mcp_server.markdown | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/_integrations/mcp_server.markdown b/source/_integrations/mcp_server.markdown index 3e274212c293..00d0ba31c050 100644 --- a/source/_integrations/mcp_server.markdown +++ b/source/_integrations/mcp_server.markdown @@ -162,7 +162,7 @@ ChatGPT supports connecting to remote Model Context Protocol servers for Plus, P - **Token endpoint auth method**: `client_secret_post` - Under **OAuth endpoints**: - **Auth Url**: `https:///auth/authorize` - - **Token url**: `https:///auth/token` + - **Token URL**: `https:///auth/token` - **Authorization server base**: `https://` 4. Select **Create**. Once created, the app will appear in your **Enabled Apps**. 5. Begin a new chat in ChatGPT, open the apps menu, and select your newly created Home Assistant app. ChatGPT will prompt you to authenticate, which will redirect you to Home Assistant to log in and authorize the connection. From ac6dc35ef39c01981aa4fb58592e02a82a9572fa Mon Sep 17 00:00:00 2001 From: c0ffeeca7 <38767475+c0ffeeca7@users.noreply.github.com> Date: Mon, 4 May 2026 08:33:08 +0200 Subject: [PATCH 4/5] typo Co-authored-by: c0ffeeca7 <38767475+c0ffeeca7@users.noreply.github.com> --- source/_integrations/mcp_server.markdown | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/_integrations/mcp_server.markdown b/source/_integrations/mcp_server.markdown index 00d0ba31c050..fb75618c5bae 100644 --- a/source/_integrations/mcp_server.markdown +++ b/source/_integrations/mcp_server.markdown @@ -310,9 +310,9 @@ To understand the root cause, first check debug logs on the client. For example 3. Select the **Home Assistant** MCP server. 4. Select **Open Logs Folder**. 5. View `mcp-server-Home Assistant.log`. These are known problems and their resolution: - - `Client error '404 Not Found' for url 'http://:8123/api/mcp'`: + - `Client error '404 Not Found' for URL 'http://:8123/api/mcp'`: this means the MCP Server integration is not configured in Home Assistant. - - `Client error '401 Unauthorized' for url 'http://:8123/api/mcp'`: + - `Client error '401 Unauthorized' for URL 'http://:8123/api/mcp'`: this means that the long-lived access token is not correct. ... From fe704e02388b4f2786bb6ff24cfd00b5ff045596 Mon Sep 17 00:00:00 2001 From: c0ffeeca7 <38767475+c0ffeeca7@users.noreply.github.com> Date: Mon, 4 May 2026 08:37:08 +0200 Subject: [PATCH 5/5] URL --- source/_integrations/mcp_server.markdown | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/_integrations/mcp_server.markdown b/source/_integrations/mcp_server.markdown index fb75618c5bae..a1d419de82c5 100644 --- a/source/_integrations/mcp_server.markdown +++ b/source/_integrations/mcp_server.markdown @@ -161,7 +161,7 @@ ChatGPT supports connecting to remote Model Context Protocol servers for Plus, P - **OAuth Client Secret**: Enter any random text (it is not used by Home Assistant, but the ChatGPT configuration form may require a value). - **Token endpoint auth method**: `client_secret_post` - Under **OAuth endpoints**: - - **Auth Url**: `https:///auth/authorize` + - **Auth URL**: `https:///auth/authorize` - **Token URL**: `https:///auth/token` - **Authorization server base**: `https://` 4. Select **Create**. Once created, the app will appear in your **Enabled Apps**.