# 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*