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                   …