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