From f8e0544e1c09872e77c2f95575b1cc1fee8e3e73 Mon Sep 17 00:00:00 2001 From: David Poll Date: Fri, 5 Dec 2025 11:09:50 -0800 Subject: [PATCH 1/8] Revise Claude for Desktop MCP server connection guide Updated the instructions for connecting Claude for Desktop to Home Assistant via remote MCP servers. Removed outdated steps and clarified the setup process. --- source/_integrations/mcp_server.markdown | 53 +++++++----------------- 1 file changed, 15 insertions(+), 38 deletions(-) diff --git a/source/_integrations/mcp_server.markdown b/source/_integrations/mcp_server.markdown index 3d4619ea866f..9dd931717183 100644 --- a/source/_integrations/mcp_server.markdown +++ b/source/_integrations/mcp_server.markdown @@ -97,44 +97,21 @@ For more information about Authentication in Home Assistant, refer to the [Authe ### Example: Claude for Desktop -See [MCP Quickstart: For Claude Desktop Users](https://modelcontextprotocol.io/quickstart/user#for-claude-desktop-users) -for a detailed guide on using Claude for Desktop with an MCP server. It is recommended -to get the example server working first before using the Home Assistant MCP Server. - -Claude for Desktop currently only supports local MCP servers using the [stdio](https://modelcontextprotocol.io/docs/concepts/transports#standard-input-output-stdio) -transport, run as a local command line tool. You can use a local MCP proxy server -to allow Claude for Desktop to access Home Assistant using the SSE transport. - -1. Download [Claude for Desktop](https://claude.ai/download). -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 configuration file. Visit **Settings…** and on the **Developer** tab, select **Edit Config**. - which will edit `claude_desktop_config.json`. The full file location depends on your - operating system (macOS or Windows). -4. Add a new MCP server to the JSON file. You need to set the `SSE_URL` to the URL you use to - connect to Home Assistant with the path `/api/mcp`. You will also need to set `API_ACCESS_TOKEN` - to the long live access token created above in the [access control instructions](#access-control) - ```json - { - "mcpServers": { - "Home Assistant": { - "command": "mcp-proxy", - "args": [ - "--transport=streamablehttp", - "--stateless", - "http://localhost:8123/api/mcp" - ], - "env": { - "API_ACCESS_TOKEN": "" - } - } - } - } - ``` -5. Restart Claude. -6. You will see a connection icon {% icon "mdi:connection" %} if things are set up correctly. Clicking the connection icon will show enabled MCP servers such as *Home Assistant*. -7. Select the prompt provided by Home Assistant. -8. You can then use Claude to control Home Assistant similar to how you control Home Assistant through the Voice Assistant. Claude wil ask you for permission before calling any tools. +Claude for Desktop now supports remote MCP servers, making it extremely easy to connect to your +Home Assistant instance: + +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" +4. Enter the following details: + * Name: "Home Assistant" (or any more descriptive name you prefer) + * Remote MCP Server URL: https:///api/mcp + * Under advanced settings: + * OAuth Client ID: https://claude.ai + * OAuth Client Secret: +5. Click OK. Now click "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 similar to how you would 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) From d4219bde452a3370aa912227277de85aeba4000f Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 5 Dec 2025 19:26:26 +0000 Subject: [PATCH 2/8] Initial plan From ba6a50f374d7ef6fe5aa184b1bdd6e9efbace676 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 5 Dec 2025 19:31:04 +0000 Subject: [PATCH 3/8] Address PR feedback: Bold UI strings and fix formatting Co-authored-by: depoll <1392690+depoll@users.noreply.github.com> --- package-lock.json | 3 --- source/_integrations/mcp_server.markdown | 20 ++++++++++---------- 2 files changed, 10 insertions(+), 13 deletions(-) diff --git a/package-lock.json b/package-lock.json index d0299926aec6..99dbf11b42dd 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1594,7 +1594,6 @@ "integrity": "sha512-hIS4idWWai69NezIdRt2xFVofaF4j+6INOpJlVOLDO8zXGpUVEVzIYk12UUi2JzjEzWL3IOAxcTubgz9Po0yXw==", "dev": true, "license": "MIT", - "peer": true, "dependencies": { "accepts": "^2.0.0", "body-parser": "^2.2.1", @@ -6740,7 +6739,6 @@ "integrity": "sha512-Enhu+WpNnP30OlOBTV3cMez+fNzcsv1bV9AtIVscUMiDcF/aFfAPoXklMMGltK2fffxPVEn5pr2yFiyihJdZ+w==", "dev": true, "license": "MIT", - "peer": true, "dependencies": { "@modelcontextprotocol/sdk": "^1.22.0", "@textlint/ast-node-types": "15.4.1", @@ -8027,7 +8025,6 @@ "integrity": "sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ==", "dev": true, "license": "MIT", - "peer": true, "funding": { "url": "https://github.com/sponsors/colinhacks" } diff --git a/source/_integrations/mcp_server.markdown b/source/_integrations/mcp_server.markdown index 9dd931717183..1e331e99f4f9 100644 --- a/source/_integrations/mcp_server.markdown +++ b/source/_integrations/mcp_server.markdown @@ -101,19 +101,19 @@ Claude for Desktop now supports remote MCP servers, making it extremely easy to Home Assistant instance: 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. Click your profile name, select **Settings**, and go to **Connectors**. +3. Click **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 - * Under advanced settings: - * OAuth Client ID: https://claude.ai - * OAuth Client Secret: -5. Click OK. Now click "Connect" next to the entry created with the name you provided above. + - **Name**: "Home Assistant" (or any more descriptive name you prefer) + - **Remote MCP Server URL**: https:///api/mcp + - Under advanced settings: + - **OAuth Client ID**: https://claude.ai + - **OAuth Client Secret**: +5. Click **OK**. Now click **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 similar to how you would through the Voice Assistant. Claude will ask you for permission before calling any tools. +7. You can now enable tools from Home Assistant when chatting with Claude, allowing you to control Home Assistant similar to how you would 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) + ![Screenshot of Claude for Desktop adding an item to a Home Assistant To-do list](/images/integrations/mcp_server/claude-todo-list-control.png) ### Example: Cursor From b8b0deded69aa65c043f70b9b7d6c47b9fefecbd Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 5 Dec 2025 19:38:27 +0000 Subject: [PATCH 4/8] Revert package-lock.json changes Co-authored-by: depoll <1392690+depoll@users.noreply.github.com> --- package-lock.json | 3 +++ 1 file changed, 3 insertions(+) diff --git a/package-lock.json b/package-lock.json index 99dbf11b42dd..d0299926aec6 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1594,6 +1594,7 @@ "integrity": "sha512-hIS4idWWai69NezIdRt2xFVofaF4j+6INOpJlVOLDO8zXGpUVEVzIYk12UUi2JzjEzWL3IOAxcTubgz9Po0yXw==", "dev": true, "license": "MIT", + "peer": true, "dependencies": { "accepts": "^2.0.0", "body-parser": "^2.2.1", @@ -6739,6 +6740,7 @@ "integrity": "sha512-Enhu+WpNnP30OlOBTV3cMez+fNzcsv1bV9AtIVscUMiDcF/aFfAPoXklMMGltK2fffxPVEn5pr2yFiyihJdZ+w==", "dev": true, "license": "MIT", + "peer": true, "dependencies": { "@modelcontextprotocol/sdk": "^1.22.0", "@textlint/ast-node-types": "15.4.1", @@ -8025,6 +8027,7 @@ "integrity": "sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ==", "dev": true, "license": "MIT", + "peer": true, "funding": { "url": "https://github.com/sponsors/colinhacks" } From 5829840fdd4a048698beb2fbadf6f52313d837c0 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 5 Dec 2025 19:55:41 +0000 Subject: [PATCH 5/8] Initial plan From 972be04497220c1e8a0085752d677f9bd59f31d2 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 5 Dec 2025 20:03:02 +0000 Subject: [PATCH 6/8] Fix URL placeholder formatting with backticks and underscores Co-authored-by: depoll <1392690+depoll@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 1e331e99f4f9..d41c065b8202 100644 --- a/source/_integrations/mcp_server.markdown +++ b/source/_integrations/mcp_server.markdown @@ -105,7 +105,7 @@ Home Assistant instance: 3. Click **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**: From df619d33ee70a40fde17cd22b2da6f1885af9497 Mon Sep 17 00:00:00 2001 From: David Poll Date: Fri, 5 Dec 2025 13:33:12 -0800 Subject: [PATCH 7/8] Fix style for "Leave this blank" --- 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 d41c065b8202..17359bd511b5 100644 --- a/source/_integrations/mcp_server.markdown +++ b/source/_integrations/mcp_server.markdown @@ -108,7 +108,7 @@ Home Assistant instance: - **Remote MCP Server URL**: `https:///api/mcp` - Under advanced settings: - **OAuth Client ID**: https://claude.ai - - **OAuth Client Secret**: + - **OAuth Client Secret**: Leave this blank 5. Click **OK**. Now click **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 similar to how you would through the Voice Assistant. Claude will ask you for permission before calling any tools. From be48441a0fffc376e1950ca7e66f49916b8009ae Mon Sep 17 00:00:00 2001 From: David Poll Date: Fri, 5 Dec 2025 14:41:05 -0800 Subject: [PATCH 8/8] Language/style tweaks. --- 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 17359bd511b5..9228d8f55345 100644 --- a/source/_integrations/mcp_server.markdown +++ b/source/_integrations/mcp_server.markdown @@ -107,11 +107,11 @@ Home Assistant instance: - **Name**: "Home Assistant" (or any more descriptive name you prefer) - **Remote MCP Server URL**: `https:///api/mcp` - Under advanced settings: - - **OAuth Client ID**: https://claude.ai + - **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. 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 similar to how you would through the Voice Assistant. Claude will ask you for permission before calling any tools. +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)