portainer-core/HOMEASSISTANT_MCP_SETUP.md

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 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:

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

proxy_set_header Host $host;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

If you experience SSE streaming issues, add:

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
• Model Context Protocol Specification
• Claude MCP Integration

---

Last Updated: 2026-02-06