Model Context Protocol (MCP) Server for Home Assistant

The Model Context Protocol (MCP) Server is a robust, secure, and high-performance bridge that integrates Home Assistant with Language Learning Models (LLMs), enabling natural language control and real-time monitoring of your smart home devices. Unlock advanced automation, control, and analytics for your Home Assistant ecosystem.

Table of Contents

• Overview
• Key Features
• Architecture & Design
• Installation
  • Basic Setup
  • Docker Setup (Recommended)
• Usage
• API & Documentation
• Development
• Roadmap & Future Plans
• Community & Support
• Contributing
• Troubleshooting & FAQ
• License

Overview

The MCP Server bridges Home Assistant with advanced LLM integrations to deliver intuitive control, automation, and state monitoring. Leveraging a high-performance runtime and real-time communication protocols, MCP offers a seamless experience for managing your smart home.

Key Features

Device Control & Monitoring

• Smart Device Control: Manage lights, climate, covers, switches, sensors, media players, fans, locks, vacuums, and cameras using natural language commands.
• Real-time Updates: Receive instant notifications and updates via Server-Sent Events (SSE).

System & Automation Management

• Automation Engine: Create, modify, and trigger custom automation rules with ease.
• Add-on & Package Management: Integrates with HACS for deploying custom integrations, themes, scripts, and applications.
• Robust System Management: Features advanced state monitoring, error handling, and security safeguards.

Architecture & Design

The MCP Server is built with scalability, resilience, and security in mind:

• High-Performance Runtime: Powered by Bun for fast startup, efficient memory utilization, and native TypeScript support.
• Real-time Communication: Employs Server-Sent Events (SSE) for continuous, real-time data updates.
• Modular & Extensible: Designed to support plugins, add-ons, and custom automation scripts, allowing for easy expansion.
• Secure API Integration: Implements token-based authentication, rate limiting, and adherence to best security practices.

For a deeper dive into the system architecture, please refer to our Architecture Documentation.

Installation

Basic Setup

1. Install Bun: If Bun is not installed:

   curl -fsSL https://bun.sh/install | bash
   

2. Clone the Repository:

   git clone https://github.com/jango-blockchained/homeassistant-mcp.git
   cd homeassistant-mcp
   

3. Install Dependencies:

   bun install
   

4. Build the Project:

   bun run build
   

Docker Setup (Recommended)

1. Clone the Repository:

   git clone https://github.com/jango-blockchained/homeassistant-mcp.git
   cd homeassistant-mcp
   

2. Configure Environment:

   cp .env.example .env
   

   Customize the .env file with your Home Assistant configuration.

3. Deploy with Docker Compose:

   docker compose up -d
   

   • View logs: docker compose logs -f
   • Stop the server: docker compose down

4. Update the Application:

   git pull && docker compose up -d --build
   

Usage

Once the server is running, open your browser at http://localhost:3000. For real-time device updates, integrate the SSE endpoint in your application:

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);
};

API & Documentation

Access comprehensive API details and guides in the docs directory:

• API Reference: API Documentation
• SSE Documentation: SSE API
• Troubleshooting Guide: Troubleshooting
• Architecture Details: Architecture Documentation

Development

Running in Development Mode

bun run dev

Running Tests

• Execute all tests:

  bun test
  

• Run tests with coverage:

  bun test --coverage
  

Production Build & Start

bun run build
bun start

Roadmap & Future Plans

The MCP Server is under active development and improvement. Planned enhancements include:

• Advanced Automation Capabilities: Introducing more complex automation rules and conditional logic.
• Enhanced Security Features: Additional authentication layers, encryption enhancements, and security monitoring tools.
• User Interface Improvements: Development of a more intuitive web dashboard for easier device management.
• Expanded Integrations: Support for a wider array of smart home devices and third-party services.
• Performance Optimizations: Continued efforts to reduce latency and improve resource efficiency.

For additional details, check out our Roadmap.

Community & Support

Join our community to stay updated, share ideas, and get help:

• GitHub Issues: Report bugs or suggest features on our GitHub Issues Page.
• Discussion Forums: Connect with other users and contributors in our community forums.
• Chat Platforms: Join our real-time discussions on Discord or Slack.

Contributing

We welcome your contributions! To get started:

1. Fork the repository.
2. Create your feature branch:

   git checkout -b feature/your-feature-name
   

3. Install dependencies:

   bun install
   

4. Make your changes and run tests:

   bun test
   

5. Commit and push your changes, then open a Pull Request.

For detailed guidelines, see Contributing Guide.

Troubleshooting & FAQ

Common Issues

• Connection Problems: Ensure that your HASS_HOST, authentication token, and WebSocket URL are correctly configured.
• Docker Deployment: Confirm that Docker is running and that your .env file contains the correct settings.
• Automation Errors: Verify entity availability and review your automation configurations for potential issues.

For more troubleshooting details, refer to Troubleshooting Guide.

Frequently Asked Questions

Q: What platforms does MCP Server support?

A: MCP Server runs on Linux, macOS, and Windows (Docker is recommended for Windows environments).

Q: How do I report a bug or request a feature?

A: Please use our GitHub Issues Page to report bugs or request new features.

Q: Can I contribute to the project?

A: Absolutely! We welcome contributions from the community. See the Contributing section for more details.

License

This project is licensed under the MIT License. See LICENSE for the full license text.

Documentation

Full documentation is available at: https://yourusername.github.io/your-repo-name/

Quick Start

Installation

Usage