homeassistant-mcp

# Model Context Protocol Server for Home Assistant The server uses the MCP protocol to share access to a local Home Assistant instance with an LLM application. A powerful bridge between your Home Assistant instance and Language Learning Models (LLMs), enabling natural language control and monitoring of your smart home devices through the Model Context Protocol (MCP). This server provides a comprehensive API for managing your entire Home Assistant ecosystem, from device control to system administration.       ## Features - 🎮 **Device Control**: Control any Home Assistant device through natural language - 🔄 **Real-time Updates**: Get instant updates through Server-Sent Events (SSE) - 🤖 **Automation Management**: Create, update, and manage automations - 📊 **State Monitoring**: Track and query device states - 🔐 **Secure**: Token-based authentication and rate limiting - 📱 **Mobile Ready**: Works with any HTTP-capable client ## Real-time Updates with SSE The server includes a powerful Server-Sent Events (SSE) system that provides real-time updates from your Home Assistant instance. This allows you to: - 🔄 Get instant state changes for any device - 📡 Monitor automation triggers and executions - 🎯 Subscribe to specific domains or entities - 📊 Track service calls and script executions ### Quick SSE Example ```javascript const eventSource = new EventSource( 'http://localhost:3000/subscribe_events?token=YOUR_TOKEN&domain=light' ); eventSource.onmessage = (event) => { const data = JSON.parse(event.data); console.log('Update received:', data); }; ``` See [SSE_API.md](docs/SSE_API.md) for complete documentation of the SSE system. ## Table of Contents - [Key Features](#key-features) - [Prerequisites](#prerequisites) - [Installation](#installation) - [Basic Setup](#basic-setup) - [Docker Setup (Recommended)](#docker-setup-recommended) - [Configuration](#configuration) - [Development](#development) - [API Reference](#api-reference) - [Device Control](#device-control) - [Add-on Management](#add-on-management) - [Package Management](#package-management) - [Automation Management](#automation-management) - [Natural Language Integration](#natural-language-integration) - [Troubleshooting](#troubleshooting) - [Project Status](#project-status) - [Contributing](#contributing) - [Resources](#resources) - [License](#license) ## Key Features ### Core Functionality 🎮 - **Smart Device Control** - 💡 **Lights**: Brightness, color temperature, RGB color - 🌡️ **Climate**: Temperature, HVAC modes, fan modes, humidity - 🚪 **Covers**: Position and tilt control - 🔌 **Switches**: On/off control - 🚨 **Sensors & Contacts**: State monitoring - 🎵 **Media Players**: Playback control, volume, source selection - 🌪️ **Fans**: Speed, oscillation, direction - 🔒 **Locks**: Lock/unlock control - 🧹 **Vacuums**: Start, stop, return to base - 📹 **Cameras**: Motion detection, snapshots ### System Management 🛠️ - **Add-on Management** - Browse available add-ons - Install/uninstall add-ons - Start/stop/restart add-ons - Version management - Configuration access - **Package Management (HACS)** - Integration with Home Assistant Community Store - Multiple package types support: - Custom integrations - Frontend themes - Python scripts - AppDaemon apps - NetDaemon apps - Version control and updates - Repository management - **Automation Management** - Create and edit automations - Advanced configuration options: - Multiple trigger types - Complex conditions - Action sequences - Execution modes - Duplicate and modify existing automations - Enable/disable automation rules - Trigger automation manually ### Architecture Features 🏗️ - **Intelligent Organization** - Area and floor-based device grouping - State monitoring and querying - Smart context awareness - Historical data access - **Robust Architecture** - Comprehensive error handling - State validation - Secure API integration - TypeScript type safety - Extensive test coverage ## Prerequisites - **Node.js** 20.10.0 or higher - **NPM** package manager - **Docker Compose** for containerization - Running **Home Assistant** instance - Home Assistant long-lived access token ([How to get token](https://community.home-assistant.io/t/how-to-get-long-lived-access-token/162159)) - **HACS** installed for package management features - **Supervisor** access for add-on management ## Installation ### Basic Setup ```bash # Clone the repository git clo