Skip to content
57 changes: 17 additions & 40 deletions source/_integrations/mcp_server.markdown
Original file line number Diff line number Diff line change
Expand Up @@ -97,46 +97,23 @@ 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": "<your_access_token_here>"
}
}
}
}
```
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.

![Screenshot of Claude for Desktop adding an item to a Home Assistant To-do list](/images/integrations/mcp_server/claude-todo-list-control.png)
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://<your_home_assistant_url>/api/mcp`
- Under advanced settings:
- **OAuth Client ID**: https://claude.ai
- **OAuth Client Secret**: <leave 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.

![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

Expand Down