diff --git a/HOMEASSISTANT_MCP_SETUP.md b/HOMEASSISTANT_MCP_SETUP.md
new file mode 100644
index 0000000..017c13a
--- /dev/null
+++ b/HOMEASSISTANT_MCP_SETUP.md
@@ -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*