📌Overview

Purpose: The Model Context Protocol Server aims to facilitate seamless interaction between a Home Assistant instance and Language Learning Models (LLMs) through natural language control and comprehensive device management.

Overview: This server acts as a robust bridge, utilizing the Model Context Protocol (MCP) to provide an API for controlling and monitoring smart home devices. It enhances user experience by allowing real-time updates and sophisticated automation management from any HTTP-capable client.

Key Features:

Device Control: enables natural language commands for controlling various Home Assistant devices like lights, climate systems, and media players, making smart home management intuitive.
Real-time Updates: powered by Server-Sent Events (SSE), this feature delivers instant notifications for device state changes, automation triggers, and service executions, ensuring users are always informed.
Automation Management: provides tools to create, modify, and manage complex automations, allowing users to tailor their smart home experience according to personal preferences and routines.
Secure Access: features token-based authentication and rate limiting to protect user data and prevent abuse of the API.
Mobile Compatibility: optimized for any HTTP-capable client, facilitating accessibility and usability across devices.

Model Context Protocol Server for Home Assistant

The Model Context Protocol (MCP) server functions as a bridge between your Home Assistant instance and Language Learning Models (LLMs), enabling natural language control and monitoring of smart home devices.

Features

Device Control: Control Home Assistant devices through natural language.
Real-time Updates: Instant updates via Server-Sent Events (SSE).
Automation Management: Create and manage automations easily.
State Monitoring: Track and query device states.
Secure: Token-based authentication with rate limiting.
Mobile Ready: Compatible with any HTTP-capable client.

Real-time Updates with SSE

The server supports SSE for real-time updates from your Home Assistant instance.

Quick SSE Example

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

Refer to 1 for detailed documentation.

Key Features
Prerequisites
Installation
Configuration
Development
API Reference
Troubleshooting
Project Status
Contributing
License

Key Features

Core Functionality

Smart Device Control
- Controls for various devices like lights, climate, covers, switches, sensors, media players, fans, locks, vacuums, and cameras.

System Management

Add-on Management: Install, browse, and manage add-ons.
Package Management: Integration with Home Assistant Community Store (HACS).
Automation Management: Create and modify automations with advanced configurations.

Prerequisites

Node.js 20.10.0 or higher
NPM package manager
Docker Compose for containerization
Active Home Assistant instance
Home Assistant long-lived access token
HACS installed for package management
Supervisor access for add-on management

Installation

Basic Setup

git clone https://github.com/jango-blockchained/homeassistant-mcp.git
cd homeassistant-mcp
npm install
npm run build

Docker Setup (Recommended)

Clone the repository:

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

Configure environment:
```
cp .env.example .env
```
Edit the .env file to include your Home Assistant configuration.

Build and run with Docker Compose:

docker compose up -d
docker compose logs -f

Verify the installation: Access the server at http://localhost:3000.
Update the application:
```
git pull
docker compose up -d --build
```

Configuration

Environment Variables

HASS_HOST=http://homeassistant.local:8123 
HASS_TOKEN=your_home_assistant_token
HASS_SOCKET_URL=ws://homeassistant.local:8123/api/websocket
PORT=3000
NODE_ENV=production
DEBUG=false

Adding to Claude Desktop (or other clients)

{
  "homeassistant": {
    "command": "node",
    "args": ["<path/to/your/dist/folder>"],
    "env": {
      "NODE_ENV": "development",
      "HASS_HOST": "http://homeassistant.local:8123",
      "HASS_TOKEN": "your_home_assistant_token",
      "PORT": 3000,
      "HASS_SOCKET_URL": "ws://homeassistant.local:8123/api/websocket",
      "LOG_LEVEL": "debug"
    }
  }
}

API Reference

Device Control Example

Common Entity Control

{
  "tool": "control",
  "command": "turn_on",
  "entity_id": "light.living_room"
}

Automation Management Example

{
  "tool": "automation_config",
  "action": "create",
  "config": {
    "alias": "Motion Light",
    "trigger": [{
      "platform": "state",
      "entity_id": "binary_sensor.motion",
      "to": "on"
    }],
    "action": [{
      "service": "light.turn_on",
      "target": {"entity_id": "light.living_room"}
    }]
  }
}

Development

npm run dev   # Development mode with hot reload
npm run build # Build project
npm run test  # Run tests
npm run lint  # Lint code
npm run format # Format code

Troubleshooting

Common Issues

Node.js Version: Ensure Node.js is updated to version 20.10.0+.
Connection Issues: Verify the accessibility of HASS_HOST and token permissions.

Project Status

✅ Complete: Basic functionalities and integration with Home Assistant.

🚧 In Progress: WebSocket real-time updates and enhanced security features.

Contributing

Fork the repository.
Create a feature branch.
Implement your changes and add tests.
Submit a pull request.

License

MIT License - See LICENSE file.

homeassistant-mcp