# McpHomeAssistant
## 基本信息
- Slug: `jonathan97480-mcphomeassistant`
- Source: modelscope
- Publisher: @Jonathan97480/McpHomeAssistant
- Categories: home-automation-and-iot / agent-orchestration / app-automation
- Hosted: No
- License: MIT License
- Source URL: https://www.modelscope.cn/mcp/servers/@Jonathan97480/McpHomeAssistant
## 简介
暂无描述。
## 安装提示

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

## MCP Server 详情

#  Home Assistant MCP Server

[![MCP](https://img.shields.io/badge/MCP-Compatible-green)](https://modelcontextprotocol.io/)
[![Python](https://img.shields.io/badge/Python-3.8+-blue)](https://www.python.org/)
[![Home Assistant](https://img.shields.io/badge/Home%20Assistant-Compatible-orange)](https://www.home-assistant.io/)
[![Phase](https://img.shields.io/badge/Phase%203.4-Complete-brightgreen)](docs/PHASE_3_4_SUMMARY.md)

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](#version-franaise) | [ Documentation](docs/) | [ Tests](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:**
```bash
curl -fsSL https://raw.githubusercontent.com/Jonathan97480/McpHomeAssistant/master/install.sh | bash
```

**Manual Installation:**
```bash
git clone https://github.com/Jonathan97480/McpHomeAssistant.git
cd McpHomeAssistant
chmod +x install.sh
./install.sh
```

### Quick HTTP Server Start

```bash
# 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:**
```bash
# 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](docs/HTTP_SERVER_README.md)**

###  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                   …