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 (if available).

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.md
• Architecture Details: Architecture Documentation (if available)

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 (if available).

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.md.

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.md.

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.