🏠 Home Assistant MCP

Bridge the gap between AI assistants and your smart home 🚀

A powerful, secure, and extensible Model Context Protocol (MCP) server that enables AI assistants like Claude, GPT, and Cursor to seamlessly interact with Home Assistant. Control your lights, climate, automations, and more through natural language commands.

✨ Feature Overview

🤖 AI-Powered Smart Home Control

Natural Language Processing: Turn "dim the living room lights to 50%" into actual device commands
Multi-Assistant Support: Works with Claude, GPT-4, Cursor, and other MCP-compatible assistants
Intelligent Context: Remembers device states, relationships, and user preferences

🛡️ Enterprise-Grade Security

Rate Limiting: Protects against abuse with configurable request limits
Input Sanitization: Prevents XSS and injection attacks
JWT Authentication: Secure token-based access control
Security Headers: Comprehensive protection against web vulnerabilities

⚡ High-Performance Architecture

Bun Runtime: 4x faster than Node.js with built-in TypeScript support
Streaming Responses: Real-time updates for long-running operations
Modular Design: Clean separation of concerns with extensible plugin system
Multiple Transports: HTTP REST API, WebSocket, and Standard I/O support

🏠 Comprehensive Device Control

Lighting Control: Brightness, color temperature, RGB colors, and effects
Climate Management: Thermostats, HVAC modes, fan control, and scheduling
Automation & Scenes: Trigger automations, activate scenes, and manage routines
Device Discovery: Intelligent device listing with filtering and search
Notification System: Send alerts through Home Assistant's notification channels

🎙️ Voice & AI Integration

Speech-to-Text: Whisper model integration for voice commands
Wake Word Detection: Always-listening capabilities with custom wake words
NLP Processing: Advanced intent recognition and entity extraction
Context Awareness: Learns from usage patterns and user behavior

🚀 Quick Start

Get up and running in minutes:

# Clone and install
git clone https://github.com/jango-blockchained/homeassistant-mcp.git
cd homeassistant-mcp
bun install

# Configure environment
cp .env.example .env
# Edit .env with your Home Assistant details

# Start the server
bun run start:stdio

That's it! Your AI assistant can now control your smart home. 🤖✨

📦 Installation

Prerequisites

🚀 Bun (v1.0.26+) - Recommended
🏠 Home Assistant instance
🐳 Docker (optional, for speech features)

Option 1: NPX (Easiest)

npx @jango-blockchained/homeassistant-mcp@latest

Option 2: Bunx with GitHub (No NPM Login Required)

If you can't login to npm, use Bunx to run directly from GitHub:

# Install Bun first if you don't have it
curl -fsSL https://bun.sh/install | bash

# Then run from GitHub
bunx github:jango-blockchained/homeassistant-mcp

Alternatively, install directly from Git:

bun add git+https://github.com/jango-blockchained/homeassistant-mcp.git
homeassistant-mcp

Option 3: Local Installation

# Install globally
bun add -g @jango-blockchained/homeassistant-mcp

# Or locally
bun add homeassistant-mcp

# Run
homeassistant-mcp

Option 4: From Source (Most Flexible)

git clone https://github.com/jango-blockchained/homeassistant-mcp.git
cd homeassistant-mcp
bun install
bun run build
bun run start:stdio

🛠️ Usage

AI Assistant Integration

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "homeassistant-mcp": {
      "command": "npx",
      "args": ["@jango-blockchained/homeassistant-mcp@latest"]
    }
  }
}

Or if you can't login to npm, use bunx:

{
  "mcpServers": {
    "homeassistant-mcp": {
      "command": "bunx",
      "args": ["github:jango-blockchained/homeassistant-mcp"]
    }
  }
}

VS Code + Claude Extension

The .vscode/settings.json is pre-configured for immediate use.

Cursor

Add to .cursor/config/config.json:

{
  "mcpServers": {
    "homeassistant-mcp": {
      "command": "npx",
      "args": ["@jango-blockchained/homeassistant-mcp@latest"]
    }
  }
}

Or with bunx:

{
  "mcpServers": {
    "homeassistant-mcp": {
      "command": "bunx",
      "args": ["github:jango-blockchained/homeassistant-mcp"]
    }
  }
}

API Usage

Start the HTTP server:

bun run start -- --http

Available endpoints:

POST /api/tools/call - Execute tools
GET /api/resources/list - List resources
GET /api/health - Health check
WebSocket /api/ws - Real-time updates

Configuration

Create a .env file:

# Home Assistant
HASS_HOST=http://your-ha-instance:8123
HASS_TOKEN=your_long_lived_access_token

# Server
PORT=3000
NODE_ENV=production

# Security
JWT_SECRET=your-secret-key
RATE_LIMIT_WINDOW=15
RATE_LIMIT_MAX=50

🏗️ Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   AI Assistant  │◄──►│   MCP Server    │◄──►│ Home Assistant  │
│  (Claude/GPT)   │    │                 │    │                 │
└─────────────────┘    │ ┌─────────────┐ │    └─────────────────┘
                       │ │  Transport  │ │
                       │ │   Layer     │ │
                       │ └─────────────┘ │
                       │ ┌─────────────┐ │
                       │ │ Middleware  │ │
                       │ │   Layer     │ │
                       │ └─────────────┘ │
                       │ ┌─────────────┐ │
                       │ │   Tools     │ │
                       │ │   Layer     │ │
                       └─────────────────┘

Core Components

Transport Layer: HTTP, WebSocket, Stdio
Middleware Layer: Security, validation, logging
Tools Layer: Device control, automation, notifications
Resource Manager: State management and caching

Built-in Tools

🔦 Lights Control: Full spectrum lighting management
🌡️ Climate Control: HVAC and thermostat operations
⚙️ Automation: Scene and automation triggers
📱 Notifications: Multi-channel alert system
📋 Device Management: Discovery and organization

🎯 Example Commands

Once integrated, your AI assistant can understand commands like:

"Turn off all lights in the bedroom" "Set the thermostat to 72°F" "Activate the movie scene" "What's the current temperature in the living room?" "Notify everyone that dinner is ready"

🤝 Contributing

We welcome contributions! Here's how to get involved:

🍴 Fork the repository
🌿 Create a feature branch
💻 Make your changes
🧪 Add tests if applicable
📝 Update documentation
🔄 Submit a pull request

Development Setup

bun install
bun run build
bun test

Code Style

TypeScript with strict mode
ESLint for code quality
Prettier for formatting
Husky for pre-commit hooks

📄 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

Built with ❤️ using:

Bun - The fast JavaScript runtime
Home Assistant - The open-source home automation platform
Model Context Protocol - The AI integration standard

Transform your smart home into an AI-powered experience

家庭助手