docs(home-assistant): add MCP server setup guide for Claude integration
Documents the configuration steps for connecting Claude.ai and Claude Desktop to Home Assistant via the Model Context Protocol (MCP) server endpoint. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Claude Opus 4.5
@@ -0,0 +1,191 @@
|
|||||||
|
# Home Assistant MCP Server Setup Guide
|
||||||
|
|
||||||
|
> **Created:** 2026-02-06
|
||||||
|
> **Status:** Infrastructure Ready - Manual Configuration Required
|
||||||
|
|
||||||
|
This guide documents the setup of the Home Assistant MCP (Model Context Protocol) Server integration for use with Claude.ai and Claude Desktop.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Current State
|
||||||
|
|
||||||
|
| Component | Status | Details |
|
||||||
|
|-----------|--------|---------|
|
||||||
|
| Home Assistant | Running | https://housekeeping.schweitz.net |
|
||||||
|
| MCP Endpoint | Active | https://housekeeping.schweitz.net/api/mcp |
|
||||||
|
| NPM Proxy | Configured | WebSocket support enabled, SSL via Let's Encrypt |
|
||||||
|
| Authentik | Not in path | Good - allows Home Assistant's built-in IndieAuth |
|
||||||
|
|
||||||
|
### Verified Configuration
|
||||||
|
|
||||||
|
**MCP Endpoint Test Results:**
|
||||||
|
- `GET /api/mcp` → `401 Unauthorized` (expected - requires OAuth)
|
||||||
|
- `OPTIONS /api/mcp` → CORS preflight working
|
||||||
|
- Allowed methods: GET, OPTIONS, POST
|
||||||
|
|
||||||
|
**NPM Configuration (proxy host ID 15):**
|
||||||
|
- Domain: `housekeeping.schweitz.net`
|
||||||
|
- Forward: `localhost:8123`
|
||||||
|
- WebSocket upgrade: Enabled
|
||||||
|
- SSL: Let's Encrypt (certificate ID 18)
|
||||||
|
- Advanced config includes WebSocket headers
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 1: Home Assistant Configuration
|
||||||
|
|
||||||
|
### 1.1 Verify MCP Server Integration is Enabled
|
||||||
|
|
||||||
|
The MCP endpoint is already responding, which suggests the integration may already be installed. Verify in Home Assistant:
|
||||||
|
|
||||||
|
1. Go to **Settings** → **Devices & Services**
|
||||||
|
2. Look for "Model Context Protocol Server" or "MCP Server"
|
||||||
|
3. If not present, click **Add Integration** and search for "MCP"
|
||||||
|
|
||||||
|
### 1.2 Expose Entities to Voice Assistants (Required)
|
||||||
|
|
||||||
|
The MCP server only exposes entities that are enabled for voice assistants. You must configure which entities Claude can access:
|
||||||
|
|
||||||
|
1. Go to **Settings** → **Voice assistants**
|
||||||
|
2. Click on **Assist** (the default assistant)
|
||||||
|
3. Go to the **Expose** tab
|
||||||
|
4. Enable the entities you want Claude to control:
|
||||||
|
- **Lights** - for lighting control
|
||||||
|
- **Switches** - for on/off devices
|
||||||
|
- **Climate** - for thermostats and HVAC
|
||||||
|
- **Covers** - for blinds, garage doors, etc.
|
||||||
|
- **Scenes** - for activating predefined scenes
|
||||||
|
- **Scripts** - for running custom automations
|
||||||
|
- **Media players** - for controlling media devices
|
||||||
|
- **Sensors** - for reading sensor values (read-only)
|
||||||
|
|
||||||
|
**Recommendation:** Start with a few entities to test, then expand once connectivity is verified.
|
||||||
|
|
||||||
|
### 1.3 (Optional) Generate Long-Lived Access Token
|
||||||
|
|
||||||
|
Only needed if using clients that don't support OAuth:
|
||||||
|
|
||||||
|
1. Click your user profile (your name in the sidebar)
|
||||||
|
2. Scroll down to **Long-lived access tokens**
|
||||||
|
3. Click **Create Token**
|
||||||
|
4. Name it (e.g., "Claude MCP Token")
|
||||||
|
5. Copy and save the token securely - it won't be shown again
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 2: Claude.ai Configuration
|
||||||
|
|
||||||
|
### For Claude.ai (Web Interface)
|
||||||
|
|
||||||
|
1. Go to [claude.ai](https://claude.ai) and sign in
|
||||||
|
2. Navigate to **Settings** → **Integrations** or **MCP Servers**
|
||||||
|
3. Click **Add Remote MCP Server**
|
||||||
|
4. Enter the following configuration:
|
||||||
|
- **Server URL:** `https://housekeeping.schweitz.net/api/mcp`
|
||||||
|
- **Name:** Home Assistant (or your preferred name)
|
||||||
|
5. Click **Connect** or **Add**
|
||||||
|
6. You'll be redirected to Home Assistant for OAuth authentication
|
||||||
|
7. Log in to Home Assistant and authorize Claude
|
||||||
|
8. Return to Claude.ai - the connection should now be active
|
||||||
|
|
||||||
|
### For Claude Desktop
|
||||||
|
|
||||||
|
1. Open Claude Desktop application
|
||||||
|
2. Go to **Settings** or **Preferences**
|
||||||
|
3. Navigate to **MCP Servers** or **Integrations**
|
||||||
|
4. Click **Add Remote Server**
|
||||||
|
5. Enter:
|
||||||
|
- **URL:** `https://housekeeping.schweitz.net/api/mcp`
|
||||||
|
6. Click **Connect**
|
||||||
|
7. A browser window will open for Home Assistant authentication
|
||||||
|
8. Log in and authorize the connection
|
||||||
|
9. Return to Claude Desktop - the server should appear as connected
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 3: Verification
|
||||||
|
|
||||||
|
### Test MCP Endpoint Accessibility
|
||||||
|
|
||||||
|
From command line:
|
||||||
|
```bash
|
||||||
|
# Should return 401 Unauthorized (expected without auth)
|
||||||
|
curl -I https://housekeeping.schweitz.net/api/mcp
|
||||||
|
|
||||||
|
# More detailed test
|
||||||
|
curl -v https://housekeeping.schweitz.net/api/mcp
|
||||||
|
```
|
||||||
|
|
||||||
|
### Test Claude Integration
|
||||||
|
|
||||||
|
After connecting Claude to Home Assistant, try these commands:
|
||||||
|
|
||||||
|
1. **List devices:** "What Home Assistant devices are available?"
|
||||||
|
2. **Check state:** "What's the current state of the living room lights?"
|
||||||
|
3. **Control device:** "Turn on the living room lights"
|
||||||
|
4. **Get sensor value:** "What's the current temperature inside?"
|
||||||
|
|
||||||
|
### Troubleshooting
|
||||||
|
|
||||||
|
| Issue | Possible Cause | Solution |
|
||||||
|
|-------|---------------|----------|
|
||||||
|
| Connection timeout | Network/proxy issue | Check NPM logs, verify WebSocket support |
|
||||||
|
| 401 Unauthorized | OAuth not completed | Re-authenticate through Claude settings |
|
||||||
|
| No devices visible | Entities not exposed | Enable entities in Voice assistants → Assist → Expose |
|
||||||
|
| Commands fail | Entity not exposed for control | Check entity exposure settings in Home Assistant |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Technical Details
|
||||||
|
|
||||||
|
### How MCP Authentication Works
|
||||||
|
|
||||||
|
Home Assistant uses IndieAuth (an OAuth 2.0-based protocol) for MCP authentication:
|
||||||
|
|
||||||
|
1. Claude identifies as client ID `https://claude.ai`
|
||||||
|
2. Home Assistant validates the request and presents login
|
||||||
|
3. User authenticates and authorizes Claude
|
||||||
|
4. Home Assistant issues an access token
|
||||||
|
5. Claude uses the token for subsequent API calls
|
||||||
|
|
||||||
|
### Protocol
|
||||||
|
|
||||||
|
The MCP Server uses "Streamable HTTP" protocol:
|
||||||
|
- Requests: POST with JSON-RPC 2.0 payload
|
||||||
|
- Responses: Server-Sent Events (SSE) or direct JSON
|
||||||
|
|
||||||
|
### NPM Configuration Details
|
||||||
|
|
||||||
|
Current advanced config for `housekeeping.schweitz.net`:
|
||||||
|
```nginx
|
||||||
|
proxy_set_header Host $host;
|
||||||
|
proxy_set_header Upgrade $http_upgrade;
|
||||||
|
proxy_set_header Connection "upgrade";
|
||||||
|
```
|
||||||
|
|
||||||
|
If you experience SSE streaming issues, add:
|
||||||
|
```nginx
|
||||||
|
proxy_buffering off;
|
||||||
|
proxy_cache off;
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Security Notes
|
||||||
|
|
||||||
|
1. **Authentik is NOT in front of Home Assistant** - This is intentional and required for IndieAuth OAuth to work directly with Claude
|
||||||
|
2. **Entity exposure is granular** - Only expose entities you want Claude to access
|
||||||
|
3. **OAuth tokens are temporary** - Re-authentication may be required periodically
|
||||||
|
4. **All traffic is encrypted** - SSL/TLS via Let's Encrypt
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## References
|
||||||
|
|
||||||
|
- [Home Assistant MCP Documentation](https://www.home-assistant.io/integrations/mcp_server/)
|
||||||
|
- [Model Context Protocol Specification](https://spec.modelcontextprotocol.io/)
|
||||||
|
- [Claude MCP Integration](https://docs.anthropic.com/claude/docs/mcp)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*Last Updated: 2026-02-06*
|
||||||
Reference in New Issue
Block a user