HA_MCP

This MCP server enables Claude AI to control and query your Home Assistant instance using natural language. Once the server is running and connected to Home Assistant, Claude Desktop can discover and connect to the MCP bridge, allowing you to issue conversational commands such as turning on lights, querying sensor data, adjusting climate, and controlling scenes and automations. The integration supports real-time updates via Server-Sent Events (SSE) and secure access with OAuth2 and optional SSL. To get started, install the Home Assistant add-on that provides the Claude AI MCP bridge, then connect Claude Desktop by adding a remote MCP server with the Home Assistant instance URL. After connection, you can converse with Claude to manage devices, read statuses, and operate services across your home setup. The system exposes your Home Assistant entities and services through natural language prompts, enabling a hands-free control experience.

Prerequisites:

• Node.js 20+ (for development/building the MCP server)
• Docker (optional, for containerized deployment)
• Home Assistant environment (for add-on deployment)

Install from source (local development):

# Clone the repository
git clone https://github.com/mtebusi/ha-mcp.git
cd ha-mcp

# Install dependencies for the MCP server
cd claude-ai-mcp/mcp-server
npm install

# Build TypeScript to JavaScript (if applicable)
npm run build

# Run the MCP server locally (example)
npm start

Run with Docker (containerized):

# Build Docker image (from repository root)
docker build -t claude-ai-mcp claude-ai-mcp/

# Run container
docker run -p 8123:8123 -e HA_BASE_URL=http://localhost:8123 -e CLAUDE_API_KEY=your-key claude-ai-mcp

In Home Assistant (Add-on workflow):

1. Add repository to Home Assistant: https://github.com/mtebusi/ha-mcp
2. Install the add-on: "Claude AI MCP Bridge for Smart Home Control" and start it
3. In Claude Desktop, go to Settings → Custom Connectors → Add Remote MCP Server
4. Enter your Home Assistant URL (e.g., http://homeassistant.local:8123) and connect

Prerequisites alignment:

• Ensure your Claude API key and OAuth2 credentials are configured if required by the bridge
• Configure environment variables or add-on settings as documented by the add-on for secure access
• If using Docker, expose the correct ports and ensure network accessibility to Home Assistant

Tips and common issues:

• Ensure the MCP server can reach your Home Assistant instance on the configured base URL (use localhost or a reachable IP in your network).
• If Claude cannot discover the MCP bridge automatically, verify network visibility and that the add-on is running with correct URL exposure.
• For secure deployments, enable SSL in your add-on settings and provide OAuth2 credentials as needed by Claude integration.
• Environment variables like CLAUDE_API_KEY and OAUTH2_CLIENT_* are placeholders; replace with real credentials in a secure manner.
• When building locally, use npm run build to generate JavaScript from TypeScript prior to running the server.
• If you update the MCP server code, rebuild and restart the container or Node process to apply changes.