This project provides a Model Context Protocol (MCP) server for Home Assistant, enabling LLM applications to control and monitor smart home devices via natural language. It targets developers and power users seeking to integrate their Home Assistant instances with AI models for advanced automation and interaction.

How It Works

The server acts as a bridge, exposing a comprehensive API to interact with Home Assistant entities, automations, and add-ons. It leverages Server-Sent Events (SSE) for real-time updates on device states and automation triggers. The architecture emphasizes robust error handling, state validation, and secure API integration with TypeScript type safety.

Quick Start & Requirements

• Installation: Clone the repository, install dependencies (npm install), and build (npm run build). Docker setup is recommended: clone, configure .env with Home Assistant details, and run docker compose up -d.
• Prerequisites: Node.js 20.10.0+, NPM, Docker Compose, a running Home Assistant instance, and a Home Assistant long-lived access token. HACS is required for package management features.
• Resources: Setup involves cloning, dependency installation, and configuration. Docker setup is generally faster and more consistent.
• Links: Home Assistant Docs, HA REST API, HACS Documentation, TypeScript Documentation

Highlighted Details

• Comprehensive device control for lights, climate, switches, media players, and more.
• System management capabilities including add-on and package (HACS) management.
• Advanced automation creation, duplication, and modification via API.
• Real-time state updates and event subscriptions using Server-Sent Events (SSE).
• Token-based authentication and rate limiting for API security.

Maintenance & Community

The project is actively developed, with a clear roadmap indicating ongoing work on WebSocket implementation, security enhancements, and performance optimization. Contributions are welcomed via pull requests.

Licensing & Compatibility

The project is released under the MIT License, which permits commercial use and linking with closed-source applications.

Limitations & Caveats

WebSocket implementation for real-time updates is currently in progress. Some advanced features like multi-platform desktop integration are also under development.