# homeassistant-mcp

> MCP Server

This repository provides a Model Context Protocol (MCP) server for Home Assistant, enabling natural language control and monitoring of smart home devices through an API with real-time updates and secure authentication.

## Overview

- **Category:** System Tools
- **Language:** TypeScript
- **Stars:** 575
- **Forks:** 5
- **Owner:** tevonsb
- **GitHub:** https://github.com/tevonsb/homeassistant-mcp
- **Created:** 2024-12-12T06:30:27+00:00
- **Updated:** 2025-03-28T17:11:45+00:00
- **Source:** https://model-context-protocol.com/servers/homeassistant-mcp

## Setup

## Setup

**Basic Setup**

1.  Clone the repository:
    ```bash
    git clone https://github.com/jango-blockchained/homeassistant-mcp.git
    cd homeassistant-mcp
    ```
2.  Install dependencies:
    ```bash
    npm install
    ```
3.  Build the project:
    ```bash
    npm run build
    ```

**Docker Setup (Recommended)**

1.  Clone the repository:
    ```bash
    git clone https://github.com/jango-blockchained/homeassistant-mcp.git
    cd homeassistant-mcp
    ```
2.  Configure environment:
    ```bash
    cp .env.example .env
    ```
    Edit the `.env` file with your Home Assistant configuration.
3.  Build and run with Docker Compose:
    ```bash
    # Build and start the containers
    docker compose up -d

    # View logs
    docker compose logs -f

    # Stop the service
    docker compose down
    ```
4.  Verify the installation: The server should now be running at `http://localhost:3000`.
5.  Update the application:
    ```bash
    # Pull the latest changes
    git pull

    # Rebuild and restart the containers
    docker compose up -d --build
    ```

## Tools

## Available Tools

1.  Device Control (Control any Home Assistant device through natural language)
2.  Real-time Updates (Get instant updates through Server-Sent Events (SSE))
3.  Automation Management (Create, update, and manage automations)
4.  State Monitoring (Track and query device states)
5.  Secure (Token-based authentication and rate limiting)
6.  Mobile Ready (Works with any HTTP-capable client)
7.  Add-on Management (Browse, install, uninstall, start, stop, restart add-ons, manage versions, and access configuration)
8.  Package Management (HACS) (Integration with Home Assistant Community Store with version control and updates)
9.  Intelligent Organization (Area and floor-based device grouping with smart context awareness)
10. Robust Architecture (Comprehensive error handling, state validation, secure API integration, TypeScript type safety, and extensive test coverage)