ha-mcp-bridge

Name: ha-mcp-bridge
Availability: InStock
Author: shaike1

Backup of working HA MCP Bridge multi-tenant server

GitHub

GitHub Stars

User Rating

Not Rated

Forks

Issues

Views

Favorites

README

Home Assistant MCP Server

A Model Context Protocol (MCP) server for Home Assistant integration with Claude.ai, built with pure Node.js HTTP for maximum compatibility.

🎉 Features

Pure Node.js HTTP Architecture - No Express dependencies, matches N8N MCP structure
Claude.ai Tool Discovery Fix - Implements the prompts/list hack for proper tool discovery
OAuth 2.1 + PKCE Authentication - Secure authentication flow
Real Home Assistant Integration - Connect to actual HA instances with API tokens
10 Home Assistant Tools:
- get_entities - Get all HA entities or filter by domain
- call_service - Call HA services to control devices
- get_automations - Get all HA automations
- get_lights - Get all light entities
- get_switches - Get all switch entities
- get_climate - Get climate/HVAC entities
- get_sensors - Get sensor entities
- control_lights - Control lights with actions, brightness, and color
- get_temperature_simple - Mock temperature data for testing
- test_simple - Simple test tool for connection verification
Token Management - Register and manage API tokens via a dedicated endpoint.

🚀 Quick Start

Option 1: Docker (Recommended)

# Using pre-built images from GitHub Container Registry
docker run -d \
  --name ha-mcp-server \
  -p 3000:3000 \
  -e SERVER_URL=https://your-domain.com \
  -e HA_URL=https://your-ha-instance.com \
  -e HA_TOKEN=your_ha_token \
  -e ADMIN_USERNAME=admin \
  -e ADMIN_PASSWORD=your_secure_password \
  shaikeme/ha-mcp-server:latest

Option 2: Docker Compose

# Clone repository
git clone https://github.com/shaike1/ha-mcp-bridge.git
cd ha-mcp-bridge

# Use pre-built image
docker-compose -f docker-compose.registry.yml up -d

# Or build locally
docker-compose up -d

Option 3: Home Assistant Add-on (HAOS)

Add this repository to your Home Assistant add-on store
Install "Home Assistant MCP Server" add-on
Configure with your public URL and admin password
Start the add-on
Connect to Claude.ai using the add-on URL

Option 4: Manual Installation

git clone https://github.com/shaike1/ha-mcp-bridge.git
cd ha-mcp-bridge
npm install
npm start

Connect to Claude.ai

Add MCP integration in Claude.ai
Use your SERVER_URL
Authenticate with admin credentials
Start controlling Home Assistant with Claude!

🔧 Configuration

Home Assistant Setup

Create a Long-Lived Access Token in Home Assistant:
- Go to Profile → Security → Long-Lived Access Tokens
- Create new token
- Copy the token value
Ensure your HA instance is accessible from your MCP server

MCP Server Setup

The server requires these environment variables:

PORT=3001
SERVER_URL=https://your-domain.com
ADMIN_USERNAME=admin
ADMIN_PASSWORD=your_secure_password
HA_URL=https://your-ha-instance.com
HA_TOKEN=your_ha_token_here

API Token Management

You can register a new API token using the /tokens/register endpoint:

curl -X POST -H "Content-Type: application/json" \
-d '{"description":"my-new-key","scope":"mcp"}' \
http://localhost:3007/tokens/register

🏗️ Architecture

This MCP server uses pure Node.js HTTP (no Express) to match the architecture of working MCP servers and ensure maximum compatibility with Claude.ai.

Key Components

OAuth 2.1 + PKCE Flow - Secure authentication
Claude.ai Compatibility Hacks - Implements workarounds for Claude.ai's non-standard MCP behavior
Server-Sent Events (SSE) - Real-time tool broadcasting
Home Assistant API Integration - Direct REST API calls to HA

Claude.ai Compatibility

This server implements several workarounds for Claude.ai's non-standard MCP behavior:

prompts/list Hack - Claude.ai only calls prompts/list, never tools/list
SSE Tool Broadcasting - Auto-sends tools via Server-Sent Events
Transport Declaration - Uses streamable-http transport type