🏠 Home Assistant MCP Server

MCP Python Home Assistant

A powerful Model Context Protocol (MCP) server for integrating Home Assistant with AI agents like Claude Desktop.

🍓 Raspberry Pi Ready! This server includes a standalone HTTP mode specifically designed for easy deployment on Raspberry Pi 3B+ alongside Home Assistant. The install.sh script provides automated installation optimized for Pi hardware.

🇫🇷 Version française

✨ 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 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

Create a .env file:

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

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

🤖 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:

Open LM Studio
Go to Settings > MCP Servers
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:

Open Cursor IDE
Go to Settings > AI > MCP Servers
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 personnalisées:

Option 1: HTTP Functions (Recommandé)

Importez le fichier configs/lm-studio-functions.json
Utilisez le prompt système configs/lm-studio-system-prompt.md
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 française

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

🇬🇧 English version

✨ Fonctionnalités

🏠 Lecture d'entités : Consultez l'état de tous vos appareils Home Assistant
🎮 Contrôle d'appareils : Allumer/éteindre lumières, commutateurs, etc.
📊 Historique : Accédez à l'historique des capteurs et entités
🔐 Authentification sécurisée : Utilise les tokens d'accès Home Assistant
🚀 Performance : Connexions asynchrones pour une réactivité optimale
🛠️ Services : Appelez n'importe quel service Home Assistant
🤖 Automatisations : Générez 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 :

🍓 Déploiement Raspberry Pi aux côtés de Home Assistant
🔗 Applications web et intégrations personnalisées
🚀 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
Déploiement 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 : Intégration facile avec systèmes et workflows existants
Fonctionnement autonome : Service indépendant ne nécessitant 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 énergétique
│   └── analyze_smart_plugs.py        # Analyse prises connectées
├── examples/                         # Exemples et configuration
│   ├── claude_desktop_config.json    # Configuration Claude Desktop
│   └── smart_plug_automations.py     # Automatisations des prises
├── docs/                             # Documentation
│   ├── QUICKSTART.md                 # Guide de démarrage rapide
│   └── ARCHITECTURE.md               # Architecture technique
├── .env.example                      # Exemple de configuration
└── README.md                         # Ce fichier

🚀 Installation

Options de Démarrage Rapide

🍓 Installation Raspberry Pi (Recommandée)

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 intégration IA facile
✅ Configuration Interactive : Demande le token et URL Home Assistant pendant l'installation
✅ Service Systemd : Configure automatiquement le service système pour démarrage automatique
✅ Sécurité : Permissions de fichiers appropriées et isolation du service
✅ Port 3002 : API REST HTTP accessible depuis des machines externes
✅ Optimisé Ressources : Déploiement léger adapté au matériel Pi 3B+
✅ Compatible Debian : Testé sur Raspberry Pi OS (basé Debian)

Configuration Système Requise :

Raspberry Pi 3B+ ou plus récent
Raspberry Pi OS (Debian 11+ recommandé)
Home Assistant fonctionnant sur le même Pi ou réseau
Python 3.9+ (installé automatiquement si nécessaire)
Au moins 512MB de RAM disponible

📖 Guide Complet Raspberry Pi

💻 Installation Bureau

Pour le développement ou l'installation à distance :

Prérequis

Python 3.8+
Home Assistant avec API activée
Token d'accès Home Assistant

Installation du serveur

cd homeassistant-mcp-server
pip install -e .

Configuration

Créez un fichier .env :

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

Obtenez votre token Home Assistant :
- Allez dans Home Assistant > Profil > Tokens d'accès à long terme
- Créez 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

🤖 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 :

Ouvrez LM Studio
Allez dans Paramètres > Serveurs MCP
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 :

Ouvrez Cursor IDE
Allez dans Paramètres > IA > Serveurs MCP
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 paramètres 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'intégration MCP OpenWebUI :

Installez le plugin MCP
Configurez le serveur dans les paramètres :
servers: homeassistant: command: homeassistant-mcp-server env: HASS_URL: "http://192.168.1.22:8123" HASS_TOKEN: "votre_token_ici"

Intégration Personnalisée

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 nécessiter le chemin complet vers l'exécutable
Redémarrez votre service IA après 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 énergétique
python tests/analyze_energy.py

# Analyse de vos prises connectées
python tests/analyze_smart_plugs.py

# Génération d'automatisations d'exemple
python examples/smart_plug_automations.py

💬 Utilisation

Une fois configuré, vous pouvez demander à Claude :

"Quelles sont mes lumières allumées ?"
"Éteins toutes les lumières du salon"
"Montre-moi la température de mes capteurs"
"Quel est l'historique de mon capteur de température aujourd'hui ?"
"Crée une automatisation pour allumer les lumières au coucher du soleil"
"Génère une alerte quand ma consommation énergétique dépasse 700 kWh"

🛠️ Outils disponibles

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

📋 Gestion des entités

get_entities : Liste toutes les entités avec filtrage par domaine
get_entity_state : Récupère l'état détaillé d'une entité
get_history : Historique d'une entité sur une période donnée

🎮 Contrôle des appareils

call_service : Appelle un service pour contrôler des appareils
get_services : Liste tous les services disponibles

🤖 Automatisations (Nouveau !)

create_automation : Génère des automatisations YAML prêtes à utiliser
list_automations : Liste toutes les automatisations actives
toggle_automation : Active/désactive une automatisation

💡 Exemples d'automatisations

⚡ Surveillance énergétique

- alias: "Alerte consommation élevée"
  trigger:
    - platform: numeric_state
      entity_id: sensor.kws_306wf_energie_totale
      above: 700
  action:
    - service: persistent_notification.create
      data:
        title: "⚡ Consommation Élevée"
        message: "Plus de 700 kWh consommés !"

🌅 Éclairage automatique

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

📅 Notifications programmées

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

📚 Documentation

Guide de démarrage rapide - Installation et configuration rapide
Architecture - Documentation technique détaillée
Tests - Guide des scripts de test
Exemples - Exemples et configurations

🔧 Développement

# Installation en mode développement
pip install -e ".[dev]"

# Exécuter 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

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Enables AI agents to control and monitor Home Assistant smart home devices through natural language interactions. Supports device control, entity state monitoring, history access, and automation generation with both MCP protocol and standalone HTTP REST API modes.

🏠 Home Assistant MCP Server

✨ Features

🌐 HTTP Server Mode

HTTP Endpoints

Quick HTTP Server Start

🎯 HTTP vs MCP: When to use which?

📁 Project Structure

🚀 Installation

Quick Start Options

🍓 Raspberry Pi Installation (Recommended)

💻 Desktop Installation

Prerequisites

Server Installation

Configuration

Claude Desktop Configuration

🤖 AI Service Configurations

Claude Desktop

LM Studio

Continue.dev (VS Code Extension)

Cursor IDE

Cline (VS Code Extension)

LM Studio

Custom Integration

🧪 Testing and Validation

💬 Usage

🛠️ Available Tools

📋 Entity Management

🎮 Device Control

🤖 Automations (New!)

💡 Automation Examples

⚡ Energy Monitoring

🌅 Automatic Lighting

📅 Scheduled Notifications

📚 Documentation

🔧 Development

License

Version française

✨ Fonctionnalités

🌐 Mode Serveur HTTP

📁 Structure du Projet

🚀 Installation

Options de Démarrage Rapide

🍓 Installation Raspberry Pi (Recommandée)

💻 Installation Bureau

Prérequis

Installation du serveur

Configuration

Configuration Claude Desktop

🤖 Configurations des Services d'IA

Claude Desktop

LM Studio

Continue.dev (Extension VS Code)

Cursor IDE

Cline (Extension VS Code)

OpenWebUI

Intégration Personnalisée

🧪 Tests et Validation

💬 Utilisation

🛠️ Outils disponibles

📋 Gestion des entités

🎮 Contrôle des appareils

🤖 Automatisations (Nouveau !)

💡 Exemples d'automatisations

⚡ Surveillance énergétique

🌅 Éclairage automatique

📅 Notifications programmées

📚 Documentation

🔧 Développement

Licence

New MCP Servers

MCP directory API