Home Assistant MCP

What is Home Assistant MCP about?

Home Assistant MCP provides a bridge that lets AI assistants such as Claude, GPT‑4, and Cursor interact with a Home Assistant instance. By translating natural‑language requests into Home Assistant API calls, it allows users to manage lights, climate, automations, notifications, and more without writing code.

How to use Home Assistant MCP?

1. Install – the quickest way is:

   npx @jango-blockchained/homeassistant-mcp@latest
   

   Alternatively, use Docker, Bun, or Smithery as described in the README.
2. Configure – create a .env file (or set environment variables) with your Home Assistant URL and a long‑lived access token:

   HASS_HOST=http://your-ha-instance:8123
   HASS_TOKEN=your_long_lived_access_token
   PORT=3000   # optional
   JWT_SECRET=your_secret   # optional
   

3. Start the server – for a standard HTTP/WebSocket interface:

   bun run start -- --http
   

4. Connect an AI assistant – add the MCP server to the assistant’s configuration (Claude Desktop, VS Code extension, Cursor, etc.) using the command shown in the README.

Key features of Home Assistant MCP

• Multi‑assistant support – works with Claude, GPT‑4, Cursor, and any MCP‑compatible model.
• Secure by default – JWT authentication, rate limiting, input sanitisation, and security headers.
• High‑performance Bun runtime – up to 4× faster than Node.js, with built‑in TypeScript support.
• Streaming responses – real‑time feedback for long‑running actions.
• Multiple transports – HTTP REST, WebSocket, and STDIO.
• Extensible plugin system – add custom tools or replace existing ones.
• Comprehensive device control – 24 built‑in tools covering lights, climate, media, covers, locks, fans, vacuums, alarms, scenes, automations, device discovery, notifications, history, add‑on management, HACS integration, and smart‑maintenance/scenario detection.
• Smithery one‑click deployment – optional one‑click install via smithery.ai.

Use cases of Home Assistant MCP

• Voice‑free home automation – ask an LLM to “dim the living room lights to 30%” from any chat interface.
• Context‑aware routines – “Good night” triggers lights off, locks doors, and sets the thermostat.
• Energy monitoring – ask “show my energy consumption” and receive a summary generated from Home Assistant sensor data.
• Smart maintenance – automatically detect orphaned devices, low‑battery entities, or window‑heater conflicts.
• Remote notifications – send alerts like “Dinner is ready” to all Home Assistant notification channels.
• Developer prototyping – test new automations via natural language before coding them in YAML.

FAQ from the Home Assistant MCP

Q: Do I need Node.js? A: No. The server runs on Bun, which includes its own JavaScript engine. If you prefer Node, you can still run the package via npx, but Bun is recommended for performance.

Q: How is authentication handled? A: The server expects a Home Assistant long‑lived access token (HASS_TOKEN) and optionally a JWT secret for client‑side authentication. Rate limiting and input sanitisation are enforced automatically.

Q: Can I use the server behind a reverse proxy? A: Yes. Expose the HTTP/WebSocket ports (default 3000) and configure your proxy to forward them. Security headers are added by the server, but you may add additional TLS termination at the proxy.

Q: Are there any OS restrictions? A: Bun supports Linux, macOS, and Windows. Docker images are provided for any platform that can run containers.

Q: How do I add custom tools? A: Create a new module in the tools directory and register it in the server’s configuration. The modular architecture allows hot‑reloading without restarting the whole service.

Q: What is the recommended way to keep the server up‑to‑date? A: Use the automated GitHub Actions workflow that bumps the version, publishes to npm, and pushes a new Docker image. You can also run npx @jango-blockchained/homeassistant-mcp@latest to fetch the latest release.

🏠 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
• Smithery Integration: One-click installation and deployment via Smithery.ai

🛡️ 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
• Smart Maintenance: Find orphaned devices, analyze usage patterns, energy monitoring
• Intelligent Scenarios: Auto-detect and manage nobody-home, window/heating conflicts, energy waste

---

🚀 Quick Start

Get up and running in minutes:

# Clone and install
git clone https://github.com/jango-blockchained/advanced-homeassistant-mcp.git
cd advanced-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

Option 1: Smithery.ai (Recommended for Quick Setup)

Smithery is a registry for MCP servers that makes installation incredibly easy:

# Install to Claude Desktop
npx @smithery/cli install @jango-blockchained/homeassistant-mcp --client claude

# Install to Cursor
npx @smithery/cli install @jango-blockchained/homeassistant-mcp --client cursor

# Install to VS Code
npx @smithery/cli install @jango-blockchained/homeassistant-mcp --client vscode

You'll be prompted to configure:

• Home Assistant URL
• Long-lived access token
• Optional settings (port, debug mode)

See SMITHERY_DEPLOYMENT.md for detailed deployment guide.

Option 2: NPX (Quick Start)

npx @jango-blockchained/homeassistant-mcp@latest

Option 3: 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/advanced-homeassistant-mcp

Alternatively, install directly from Git:

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

Option 4: Docker (Containerized)

Run the MCP server in a Docker container:

# Pull the latest image
docker pull ghcr.io/jango-blockchained/advanced-homeassistant-mcp:latest

# Run with environment variables
docker run -d \
  -e HOME_ASSISTANT_URL=http://your-ha-instance:8123 \
  -e HOME_ASSISTANT_TOKEN=your_long_lived_access_token \
  -p 4000:4000 \
  --name homeassistant-mcp \
  ghcr.io/jango-blockchained/advanced-homeassistant-mcp:latest

# Or use docker-compose (see docker/ directory for examples)

Available Docker tags:

• latest - Latest stable release
• 1.0.x - Specific version
• dev - Latest development build from main branch

Option 5: Local Installation

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

# Or locally
bun add homeassistant-mcp

# Run
homeassistant-mcp

Option 6: From Source (Most Flexible)

git clone https://github.com/jango-blockchained/advanced-homeassistant-mcp.git
cd advanced-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": "bunx",
      "args": ["github:jango-blockchained/advanced-homeassistant-mcp"]
    }
  }
}

Or use npx:

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

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": "bunx",
      "args": ["github:jango-blockchained/advanced-homeassistant-mcp"]
    }
  }
}

Or with npx:

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

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 (34 Total)

🎨 Aurora Sound-to-Light (10 tools) ✨ NEW!

• 🎵 Audio Analysis: Extract BPM, beats, mood, frequency data
• 🔍 Device Scanning: Find Aurora-compatible lights
• 📊 Device Profiling: Measure latency & capabilities for sync
• 🎬 Timeline Rendering: Generate pre-rendered light shows
• ▶️ Playback Control: Play/pause/stop/seek timelines
• 📋 Timeline Management: List, export, import timelines
• 📈 Status Monitoring: System status and statistics
• 🎯 Smart Synchronization: Device-specific timing compensation
• 🌈 Capability-Aware: RGB, tunable white, brightness-only support
• 🎶 Beat Detection: Lights pulse in sync with music

🎨 Aurora is a complete sound-to-light synchronization system that transforms your Home Assistant lights into a professional light show synchronized to music!

🏠 Device Control (13 tools)

• 🔦 Lights Control: Brightness, color temp, RGB, effects
• 🌡️ Climate Control: HVAC modes, temperature, fan control
• 📺 Media Players: Playback, volume, sources, sound modes
• 🪟 Covers: Blinds, curtains, garage doors, position control
• 🔒 Locks: Lock/unlock with code support
• 💨 Fans: Speed, oscillation, direction, presets
• 🤖 Vacuums: Cleaning, docking, spot clean, fan speed
• 🚨 Alarm Control: Arm/disarm modes, security management
• 🎛️ Generic Control: Universal device control interface

⚙️ Automation & Scenes (3 tools)

• 🎬 Scenes: Activate predefined scenes
• ⚙️ Automations: List, toggle, trigger automations
• 🔧 Automation Config: Create/update/delete complex automations

🔧 System Management (6 tools)

• 📋 Device Discovery: List and filter devices by domain/area
• 📱 Notifications: Multi-channel alert system
• 📊 History: Query historical state data
• 📦 Add-on Management: Install, configure, control add-ons
• 📦 Package Management: HACS integration and custom components
• 🔔 Event Subscription: Real-time SSE event streaming

🧠 Smart Features (2 tools)

• 🔧 Maintenance Tool: Spook-like maintenance features

  • Find orphaned/unavailable devices
  • Analyze light usage patterns by room
  • Monitor energy consumption
  • Device health checks with battery warnings
  • Entity cleanup recommendations

• 🧠 Smart Scenarios: Intelligent automation detection

  • Nobody home: Auto turn off lights, reduce climate
  • Window/heating conflicts: Auto disable heating
  • Energy saving: Detect daytime lights, standby power
  • Generate automation configs

📖 See Complete Tools Reference for detailed documentation

MCP Features

• 📝 Prompts: Pre-defined prompt templates for common home automation tasks

  • Morning/evening routines
  • Energy saving suggestions
  • Security setup
  • Climate optimization
  • Media control
  • Troubleshooting helpers

• 📊 Resources: Direct access to Home Assistant states and configurations

  • Device lists by type (lights, climate, sensors, etc.)
  • Area/room configurations
  • Automation and scene listings
  • Dashboard summaries with current home status

• 🛠️ 24 Comprehensive Tools: Full device control and smart automation

  • See Complete Tools Reference for all available tools
  • Device control, automation, system management, and smart features
  • Natural language to Home Assistant API translation

---

🎯 Example Commands

Once integrated, your AI assistant can understand commands like:

Device Control:

"Turn off all lights in the bedroom"
"Set the thermostat to 72°F"
"Play music on the living room speaker"
"Open the garage door"
"Lock all doors"
"Start the robot vacuum"
"Set the bedroom fan to 50%"

Automation & Scenes:

"Activate the movie scene"
"Trigger the morning routine automation"
"Show me all my automations"

Information & Monitoring:

"What's the current temperature in the living room?"
"Show me all unavailable devices"
"Which lights are currently on?"

Notifications:

"Notify everyone that dinner is ready"
"Send an alert to my phone"

Smart Maintenance:

"Check my Home Assistant health"
"Find orphaned or unavailable devices"
"Analyze my light usage patterns"
"Show me my energy consumption"
"Which devices have low battery?"

Aurora Sound-to-Light: ✨ NEW!

"Analyze this music file and sync my lights"
"Scan for lights that can do Aurora effects"
"Profile my living room lights for synchronization"
"Create a light show for this song"
"Play the timeline I just created"
"Pause the light show"
"Show me Aurora status"

Smart Scenarios:

"I'm leaving home, activate away mode"
"Are any windows open with heating on?"
"Check for energy-wasting issues"
"Turn off everything, I'm going on vacation"
"What can I do to save energy?"

You can also use prompts for guided assistance:

"Help me set up a morning routine"
"Show me energy saving tips"
"How do I control my media players?"

---

🤝 Contributing

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

1. 🍴 Fork the repository
2. 🌿 Create a feature branch
3. 💻 Make your changes
4. 🧪 Add tests if applicable
5. 📝 Update documentation
6. 🔄 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

Releases

This project uses automated releases to GitHub, npm, and Docker. See AUTOMATED_RELEASES.md for details.

Quick Release:

1. Go to Actions → Version Bump and Release
2. Click Run workflow
3. Select version bump type (patch/minor/major)
4. The system automatically:
   • 📦 Creates a GitHub release
   • 📤 Publishes to npm
   • 🐳 Builds and pushes Docker image

---

📄 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