Home Assistant MCP Server

Un serveur Model Context Protocol (MCP) puissant avec interface web complte pour intgrer Home Assistant avec les agents IA.

** Interface Web Complte !** Phase 3.4 inclut une interface web responsive avec dashboard, authentification, gestion des permissions et configuration multi-instances Home Assistant. Installation automatise pour Raspberry Pi.

** Raspberry Pi Ready!** Installation optimise pour Raspberry Pi 3B+ avec script automatis install.sh.

Version franaise | Documentation | Tests

Features

• Entity Management : Read the state of all your Home Assistant devices
• Device Control : Turn on/off lights, switches, and more
• History Access : Access sensor and entity history data
• Secure Authentication : Uses Home Assistant access tokens
• High Performance : Asynchronous connections for optimal responsiveness
• Service Calls : Call any Home Assistant service
• Smart Automations : Generate intelligent YAML automations

HTTP Server Mode

In addition to MCP protocol, this server can run as a standalone HTTP REST API server, perfect for:

• Raspberry Pi deployment alongside Home Assistant
• Web applications and custom integrations
• Microservices architecture
• Mobile apps and third-party tools
• AI agents that don't support MCP protocol directly

Why use HTTP Server mode?

• Universal compatibility: Any programming language or tool can connect via HTTP
• Direct deployment: Install directly on your Raspberry Pi running Home Assistant
• No MCP client required: Works with any HTTP client (curl, Postman, web browsers)
• REST API standard: Easy integration with existing systems and workflows
• Standalone operation: Independent service that doesn't require MCP infrastructure

HTTP Endpoints

The HTTP server provides a complete REST API interface to Home Assistant:

• GET /health - Server health check and Home Assistant connectivity status
• GET /api/entities - List all entities (with optional domain filtering like ?domain=light)
• GET /api/entities/{entity_id} - Get specific entity state and attributes
• POST /api/services/call - Call Home Assistant services (turn on/off devices, etc.)
• GET /api/history - Get entity history data with time range filtering

Use Cases:

• Web dashboards: Build custom web interfaces for Home Assistant
• Mobile apps: Create native mobile applications with HTTP API
• Automation scripts: Use any programming language to automate your home
• Third-party integrations: Connect non-MCP services to Home Assistant
• Development testing: Quick API testing with curl or Postman

Quick Installation

Automatic Installation:

curl -fsSL https://raw.githubusercontent.com/Jonathan97480/McpHomeAssistant/master/install.sh | bash

Manual Installation:

git clone https://github.com/Jonathan97480/McpHomeAssistant.git
cd McpHomeAssistant
chmod +x install.sh
./install.sh

Quick HTTP Server Start

# Install dependencies
pip install aiohttp python-dotenv

# Configure environment
cp .env.example .env
# Edit .env with your Home Assistant URL and token

# Start HTTP server
python http_server.py

Server runs on http://localhost:3002 by default and provides a complete REST API interface.

Example API calls:

# Check server health
curl http://localhost:3002/health

# List all lights
curl http://localhost:3002/api/entities?domain=light

# Turn on a light
curl -X POST http://localhost:3002/api/services/call \
  -H "Content-Type: application/json" \
  -d '{"domain": "light", "service": "turn_on", "target": {"entity_id": "light.living_room"}}'

Complete HTTP Server Guide

HTTP vs MCP: When to use which?

Use HTTP Server when:

• Installing directly on Raspberry Pi 3B+
• Building web applications or mobile apps
• Integrating with non-MCP tools and services
• Need universal compatibility across programming languages
• Creating custom dashboards or monitoring systems

Use MCP Server when:

• Working with AI agents that support MCP (Claude Desktop, etc.)
• Need structured tool-based interactions
• Want automatic tool discovery and schema validation
• Prefer conversation-based device control

Project Structure

homeassistant-mcp-server/
 src/                              # Main source code
    homeassistant_mcp_server/
        server.py                 # Main MCP server
 tests/                            # Test and analysis scripts
    test_connection.py            # Basic connection test
    test_mcp_tools.py             # Complete tools test
    test_http_server.py           # HTTP server tests
    analyze_energy.py             # Energy analysis
    analyze_smart_plugs.py        # Smart plugs analysis
 examples/                         # Examples and configuration
    claude_desktop_config.json    # Claude Desktop configuration
    smart_plug_automations.py     # Smart plug automations
 docs/                             # Documentation
    QUICKSTART.md                 # Quick start guide
    HTTP_SERVER_README.md         # HTTP server documentation
    RASPBERRY_PI_INSTALL.md       # Raspberry Pi installation
    ARCHITECTURE.md               # Technical architecture
 scripts/                          # Utility scripts
    launcher.py                   # Service launcher wrapper
    README.md                     # Scripts documentation
 http_server.py                    # Standalone HTTP server
 install.sh                        # Raspberry Pi installation script
 .env.example                      # Configuration example
 README.md                         # This file

Installation

Quick Start Options

Raspberry Pi Installation (Recommended)

Install directly on your Raspberry Pi 3B+ alongside Home Assistant:

# Download and run the installation script
curl -sSL https://raw.githubusercontent.com/Jonathan97480/McpHomeAssistant/master/install.sh | bash

# Or download and customize before running
wget https://raw.githubusercontent.com/Jonathan97480/McpHomeAssistant/master/install.sh
chmod +x install.sh
./install.sh

** Optimized for Raspberry Pi 3B+:**

• HTTP Server Setup: Installs the standalone HTTP server for easy AI integration
• Interactive Configuration: Prompts for Home Assistant token and URL during installation
• Systemd Service: Auto-configures system service for automatic startup
• Security: Proper file permissions and service isolation
• Port 3002: HTTP REST API accessible from external machines
• Resource Optimized: Lightweight deployment suitable for Pi 3B+ hardware
• Debian Compatible: Tested on Raspberry Pi OS (Debian-based)

System Requirements:

• Raspberry Pi 3B+ or newer
• Raspberry Pi OS (Debian 11+ recommended)
• Home Assistant running on the same Pi or network
• Python 3.9+ (automatically installed if needed)
• At least 512MB available RAM

Complete Raspberry Pi Guide

Desktop Installation

For development or remote installation:

Prerequisites

• Python 3.8+
• Home Assistant with API enabled
• Home Assistant access token

Server Installation

cd homeassistant-mcp-server
pip install -e .

Configuration

1. Create a .env file:

HASS_URL=http://192.168.1.22:8123
HASS_TOKEN=your_token_here

1. Get your Home Assistant token:
   • Go to Home Assistant > Profile > Long-lived access tokens
   • Create a new token
   • Copy it to the .env file

Claude Desktop Configuration

Add this to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "homeassistant": {
      "command": "homeassistant-mcp-server",
      "env": {
        "HASS_URL": "http://192.168.1.22:8123",
        "HASS_TOKEN": "your_token_here"
      }
    }
  }
}

** Complete configuration file available in examples/claude_desktop_config.json**

AI Service Configurations

Claude Desktop

Add this to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "homeassistant": {
      "command": "homeassistant-mcp-server",
      "env": {
        "HASS_URL": "http://192.168.1.22:8123",
        "HASS_TOKEN": "your_token_here"
      }
    }
  }
}

LM Studio

Configure MCP in LM Studio:

1. Open LM Studio
2. Go to Settings > MCP Servers
3. Add a new server:
   • Name: homeassistant
   • Command: homeassistant-mcp-server
   • Environment Variables:

     HASS_URL=http://192.168.1.22:8123
     HASS_TOKEN=your_token_here
     

Continue.dev (VS Code Extension)

Add to your Continue configuration (.continue/config.json):

{
  "mcpServers": {
    "homeassistant": {
      "command": "homeassistant-mcp-server",
      "env": {
        "HASS_URL": "http://192.168.1.22:8123",
        "HASS_TOKEN": "your_token_here"
      }
    }
  }
}

Cursor IDE

Add to Cursor's AI configuration:

1. Open Cursor IDE
2. Go to Settings > AI > MCP Servers
3. Add server configuration:

   {
     "name": "homeassistant",
     "command": "homeassistant-mcp-server",
     "env": {
       "HASS_URL": "http://192.168.1.22:8123",
       "HASS_TOKEN": "your_token_here"
     }
   }
   

Cline (VS Code Extension)

Configure in Cline settings:

{
  "mcpServers": {
    "homeassistant": {
      "command": "homeassistant-mcp-server",
      "args": [],
      "env": {
        "HASS_URL": "http://192.168.1.22:8123",
        "HASS_TOKEN": "your_token_here"
      }
    }
  }
}

LM Studio

LM Studio peut utiliser le serveur via des fonctions HTTP personnalises:

Option 1: HTTP Functions (Recommand)

1. Importez le fichier configs/lm-studio-functions.json
2. Utilisez le prompt systme configs/lm-studio-system-prompt.md
3. Assurez-vous que le serveur HTTP fonctionne: http://192.168.1.22:3002/health

Configuration rapide:

{
  "name": "control_light",
  "endpoint": {
    "method": "POST",
    "url": "http://192.168.1.22:3002/api/services/call",
    "body": {
      "domain": "light",
      "service": "{{action}}",
      "service_data": {"entity_id": "{{entity_id}}"}
    }
  }
}

Guide complet LM Studio
}

### OpenWebUI
For OpenWebUI MCP integration:

1. Install the MCP plugin
2. Configure server in settings:
   ```yaml
   servers:
     homeassistant:
       command: homeassistant-mcp-server
       env:
         HASS_URL: "http://192.168.1.22:8123"
         HASS_TOKEN: "your_token_here"

Custom Integration

For other MCP-compatible services, use this standard format:

{
  "servers": {
    "homeassistant": {
      "command": "homeassistant-mcp-server",
      "env": {
        "HASS_URL": "http://192.168.1.22:8123",
        "HASS_TOKEN": "your_token_here"
      }
    }
  }
}

** Configuration Notes:**

• Replace your_token_here with your actual Home Assistant token
• Update the URL if your Home Assistant runs on a different address
• Some services may require the full path to the executable
• Restart your AI service after adding the configuration

Testing and Validation

Test your installation with the provided scripts:

# Test Home Assistant connection
python tests/test_connection.py

# Complete test of all MCP tools
python tests/test_mcp_tools.py

# Analyze your energy consumption
python tests/analyze_energy.py

# Analyze your smart plugs
python tests/analyze_smart_plugs.py

# Generate example automations
python examples/smart_plug_automations.py

Usage

Once configured, you can ask Claude:

• "What lights are currently on?"
• "Turn off all the living room lights"
• "Show me the temperature from my sensors"
• "What's the temperature history for today?"
• "Create an automation to turn on lights at sunset"
• "Generate an alert when energy consumption exceeds 700 kWh"

Available Tools

The MCP server exposes 8 tools to interact with Home Assistant:

Entity Management

• get_entities : List all entities with domain filtering
• get_entity_state : Get detailed state of an entity
• get_history : Entity history over a given period

Device Control

• call_service : Call a service to control devices
• get_services : List all available services

Automations (New!)

• create_automation : Generate ready-to-use YAML automations
• list_automations : List all active automations
• toggle_automation : Enable/disable an automation

Automation Examples

Energy Monitoring

- alias: "High consumption alert"
  trigger:
    - platform: numeric_state
      entity_id: sensor.kws_306wf_energie_totale
      above: 700
  action:
    - service: persistent_notification.create
      data:
        title: " High Consumption"
        message: "More than 700 kWh consumed!"

Automatic Lighting

- alias: "Lights at sunset"
  trigger:
    - platform: sun
      event: sunset
      offset: "-00:30:00"
  action:
    - service: light.turn_on
      target:
        area_id: living_room

Scheduled Notifications

- alias: "Morning notification"
  trigger:
    - platform: time
      at: "08:00:00"
  action:
    - service: persistent_notification.create
      data:
        title: " Good Morning!"
        message: "Have a great day!"

Documentation

• Quick Start Guide - Fast installation and configuration
• Architecture - Detailed technical documentation
• Tests - Test scripts guide
• Examples - Examples and configurations

Development

# Development installation
pip install -e ".[dev]"

# Run tests
python tests/test_mcp_tools.py

# Analyze your installation
python tests/analyze_smart_plugs.py
python -m pytest

# Start the server
homeassistant-mcp-server

License

MIT

---

Version franaise

Un serveur Model Context Protocol (MCP) puissant pour intgrer Home Assistant avec des agents IA comme Claude Desktop.

English version

Fonctionnalits

• Lecture d'entits : Consultez l'tat de tous vos appareils Home Assistant
• Contrle d'appareils : Allumer/teindre lumires, commutateurs, etc.
• Historique : Accdez l'historique des capteurs et entits
• Authentification scurise : Utilise les tokens d'accs Home Assistant
• Performance : Connexions asynchrones pour une ractivit optimale
• Services : Appelez n'importe quel service Home Assistant
• Automatisations : Gnrez des automatisations YAML intelligentes

Mode Serveur HTTP

En plus du protocole MCP, ce serveur peut fonctionner comme un serveur HTTP REST API autonome, parfait pour :

• Dploiement Raspberry Pi aux cts de Home Assistant
• Applications web et intgrations personnalises
• Architecture microservices
• Applications mobiles et outils tiers
• Agents IA qui ne supportent pas directement le protocole MCP

Pourquoi utiliser le mode Serveur HTTP ?

• Compatibilit universelle : N'importe quel langage ou outil peut se connecter via HTTP
• Dploiement direct : Installation directe sur votre Raspberry Pi 3B+ avec Home Assistant
• Pas de client MCP requis : Fonctionne avec n'importe quel client HTTP (curl, Postman, navigateurs)
• Standard REST API : Intgration facile avec systmes et workflows existants
• Fonctionnement autonome : Service indpendant ne ncessitant pas d'infrastructure MCP

Structure du Projet

homeassistant-mcp-server/
 src/                              # Code source principal
    homeassistant_mcp_server/
        server.py                 # Serveur MCP principal
 tests/                            # Scripts de test et analyse
    test_connection.py            # Test connexion de base
    test_mcp_tools.py             # Test complet des outils
    analyze_energy.py             # Analyse nergtique
    analyze_smart_plugs.py        # Analyse prises connectes
 examples/                         # Exemples et configuration
    claude_desktop_config.json    # Configuration Claude Desktop
    smart_plug_automations.py     # Automatisations des prises
 docs/                             # Documentation
    QUICKSTART.md                 # Guide de dmarrage rapide
    ARCHITECTURE.md               # Architecture technique
 .env.example                      # Exemple de configuration
 README.md                         # Ce fichier

Installation

Options de Dmarrage Rapide

Installation Raspberry Pi (Recommande)

Installez directement sur votre Raspberry Pi 3B+ avec Home Assistant :

curl -sSL https://raw.githubusercontent.com/Jonathan97480/McpHomeAssistant/master/install.sh | bash

** Optimis pour Raspberry Pi 3B+ :**

• Configuration Serveur HTTP : Installe le serveur HTTP autonome pour intgration IA facile
• Configuration Interactive : Demande le token et URL Home Assistant pendant l'installation
• Service Systemd : Configure automatiquement le service systme pour dmarrage automatique
• Scurit : Permissions de fichiers appropries et isolation du service
• Port 3002 : API REST HTTP accessible depuis des machines externes
• Optimis Ressources : Dploiement lger adapt au matriel Pi 3B+
• Compatible Debian : Test sur Raspberry Pi OS (bas Debian)

Configuration Systme Requise :

• Raspberry Pi 3B+ ou plus rcent
• Raspberry Pi OS (Debian 11+ recommand)
• Home Assistant fonctionnant sur le mme Pi ou rseau
• Python 3.9+ (install automatiquement si ncessaire)
• Au moins 512MB de RAM disponible

Guide Complet Raspberry Pi

Installation Bureau

Pour le dveloppement ou l'installation distance :

Prrequis

• Python 3.8+
• Home Assistant avec API active
• Token d'accs Home Assistant

Installation du serveur

cd homeassistant-mcp-server
pip install -e .

Configuration

1. Crez un fichier .env :

HASS_URL=http://192.168.1.22:8123
HASS_TOKEN=votre_token_ici

1. Obtenez votre token Home Assistant :
   • Allez dans Home Assistant > Profil > Tokens d'accs long terme
   • Crez un nouveau token
   • Copiez-le dans le fichier .env

Configuration Claude Desktop

Ajoutez ceci votre configuration Claude Desktop (claude_desktop_config.json) :

{
  "mcpServers": {
    "homeassistant": {
      "command": "homeassistant-mcp-server",
      "env": {
        "HASS_URL": "http://192.168.1.22:8123",
        "HASS_TOKEN": "votre_token_ici"
      }
    }
  }
}

** Fichier de configuration complet disponible dans examples/claude_desktop_config.json**

Configurations des Services d'IA

Claude Desktop

Ajoutez ceci votre configuration Claude Desktop (claude_desktop_config.json) :

{
  "mcpServers": {
    "homeassistant": {
      "command": "homeassistant-mcp-server",
      "env": {
        "HASS_URL": "http://192.168.1.22:8123",
        "HASS_TOKEN": "votre_token_ici"
      }
    }
  }
}

LM Studio

Configurez MCP dans LM Studio :

1. Ouvrez LM Studio
2. Allez dans Paramtres > Serveurs MCP
3. Ajoutez un nouveau serveur :
   • Nom : homeassistant
   • Commande : homeassistant-mcp-server
   • Variables d'environnement :

     HASS_URL=http://192.168.1.22:8123
     HASS_TOKEN=votre_token_ici
     

Continue.dev (Extension VS Code)

Ajoutez votre configuration Continue (.continue/config.json) :

{
  "mcpServers": {
    "homeassistant": {
      "command": "homeassistant-mcp-server",
      "env": {
        "HASS_URL": "http://192.168.1.22:8123",
        "HASS_TOKEN": "votre_token_ici"
      }
    }
  }
}

Cursor IDE

Ajoutez la configuration AI de Cursor :

1. Ouvrez Cursor IDE
2. Allez dans Paramtres > IA > Serveurs MCP
3. Ajoutez la configuration du serveur :

   {
     "name": "homeassistant",
     "command": "homeassistant-mcp-server",
     "env": {
       "HASS_URL": "http://192.168.1.22:8123",
       "HASS_TOKEN": "votre_token_ici"
     }
   }
   

Cline (Extension VS Code)

Configurez dans les paramtres Cline :

{
  "mcpServers": {
    "homeassistant": {
      "command": "homeassistant-mcp-server",
      "args": [],
      "env": {
        "HASS_URL": "http://192.168.1.22:8123",
        "HASS_TOKEN": "votre_token_ici"
      }
    }
  }
}

OpenWebUI

Pour l'intgration MCP OpenWebUI :

1. Installez le plugin MCP
2. Configurez le serveur dans les paramtres :

   servers:
     homeassistant:
       command: homeassistant-mcp-server
       env:
         HASS_URL: "http://192.168.1.22:8123"
         HASS_TOKEN: "votre_token_ici"
   

Intgration Personnalise

Pour d'autres services compatibles MCP, utilisez ce format standard :

{
  "servers": {
    "homeassistant": {
      "command": "homeassistant-mcp-server",
      "env": {
        "HASS_URL": "http://192.168.1.22:8123",
        "HASS_TOKEN": "votre_token_ici"
      }
    }
  }
}

** Notes de Configuration :**

• Remplacez votre_token_ici par votre vrai token Home Assistant
• Mettez jour l'URL si votre Home Assistant fonctionne sur une autre adresse
• Certains services peuvent ncessiter le chemin complet vers l'excutable
• Redmarrez votre service IA aprs avoir ajout la configuration

Tests et Validation

Testez votre installation avec les scripts fournis :

# Test de connexion Home Assistant
python tests/test_connection.py

# Test complet de tous les outils MCP
python tests/test_mcp_tools.py

# Analyse de votre consommation nergtique
python tests/analyze_energy.py

# Analyse de vos prises connectes
python tests/analyze_smart_plugs.py

# Gnration d'automatisations d'exemple
python examples/smart_plug_automations.py

Utilisation

Une fois configur, vous pouvez demander Claude :

• "Quelles sont mes lumires allumes ?"
• "teins toutes les lumires du salon"
• "Montre-moi la temprature de mes capteurs"
• "Quel est l'historique de mon capteur de temprature aujourd'hui ?"
• "Cre une automatisation pour allumer les lumires au coucher du soleil"
• "Gnre une alerte quand ma consommation nergtique dpasse 700 kWh"

Outils disponibles

Le serveur MCP expose 8 outils pour interagir avec Home Assistant :

Gestion des entits

• get_entities : Liste toutes les entits avec filtrage par domaine
• get_entity_state : Rcupre l'tat dtaill d'une entit
• get_history : Historique d'une entit sur une priode donne

Contrle des appareils

• call_service : Appelle un service pour contrler des appareils
• get_services : Liste tous les services disponibles

Automatisations (Nouveau !)

• create_automation : Gnre des automatisations YAML prtes utiliser
• list_automations : Liste toutes les automatisations actives
• toggle_automation : Active/dsactive une automatisation

Exemples d'automatisations

Surveillance nergtique

- alias: "Alerte consommation leve"
  trigger:
    - platform: numeric_state
      entity_id: sensor.kws_306wf_energie_totale
      above: 700
  action:
    - service: persistent_notification.create
      data:
        title: " Consommation leve"
        message: "Plus de 700 kWh consomms !"

clairage automatique

- alias: "Lumires au coucher du soleil"
  trigger:
    - platform: sun
      event: sunset
      offset: "-00:30:00"
  action:
    - service: light.turn_on
      target:
        area_id: salon

Notifications programmes

- alias: "Notification matinale"
  trigger:
    - platform: time
      at: "08:00:00"
  action:
    - service: persistent_notification.create
      data:
        title: " Bonjour !"
        message: "Bonne journe !"

Structure du Projet

McpHomeAssistant/
  docs/                    #  Documentation complte
    DEPLOYMENT_GUIDE.md     # Guide de dploiement
    PHASE_3_4_README.md     # Documentation Phase 3.4
    QUICK_INSTALL_RPI.md    # Installation rapide
    ...                     # Autres guides
  tests/                   #  Suite de tests
    test_simple.py          # Tests rapides
    test_complete.py        # Tests complets
    test_web_interface.py   # Tests interface web
    ...                     # Autres tests
  web/                     #  Interface Web Phase 3.4
    static/css/main.css     # Framework CSS responsive
    static/js/dashboard.js  # SPA JavaScript
    templates/              # Templates HTML
  src/                     #  Code source principal
  configs/                 #  Configurations
  examples/                #  Exemples d'usage
  install.sh               # Script installation unifi
  bridge_server.py         # Serveur principal
  start_server.py          # Script de dmarrage
  README.md                # Ce fichier

Documentation

Installation et Dploiement

• Guide de dploiement complet - Installation production
• Installation rapide Raspberry Pi - Guide express
• Installation dtaille Pi - Guide complet Pi

Architecture et Dveloppement

• Architecture systme - Documentation technique
• API REST - Documentation API complte
• Phase 3.4 - Interface web complte

Tests et Validation

• Guide des tests - Suite de tests complte
• Examples d'usage - Exemples pratiques

Dveloppement

# Installation en mode dveloppement
pip install -e ".[dev]"

# Excuter les tests
python tests/test_mcp_tools.py

# Analyser votre installation
python tests/analyze_smart_plugs.py
python -m pytest

# Lancement du serveur
homeassistant-mcp-server

Licence

MIT