🏠 家庭助理MCP服务器
   
强大的模型上下文协议(MCP)服务器 完整的web界面 将Home Assistant与AI代理集成。
完整的web界面! 阶段3.4包括一个响应式web界面,包括仪表板、身份验证、权限管理和Home Assistant多实例配置。Raspberry Pi的自动安装。
🍓 Raspberry Pi准备好了! 使用自动脚本优化Raspberry Pi 3b+安装 install.sh.✨ 特性
- 🏠 实体管理 :读取所有家庭助理设备的状态
- 🎮 设备控制 :打开/关闭灯、开关等
- 📊 历史访问 :访问传感器和实体历史数据
- 🔐 安全认证 :使用家庭助理访问令牌
- 🚀 高性能 :异步连接可实现最佳响应
- 🛠️ 服务呼叫 :致电任何家庭助理服务
- 🤖 智能自动化 :生成智能YAML自动化
🌐 HTTP服务器模式
除了MCP协议外,此服务器还可以作为独立的HTTP REST API服务器运行,非常适合:
- 🍓 Raspberry Pi部署 与家庭助理一起
- 🔗 Web应用程序 以及自定义集成
- 🚀 微服务 建筑
- 📱 移动应用 第三方工具
- 🤖 AI代理 不直接支持MCP协议
为什么使用HTTP服务器模式?
- 通用兼容性:任何编程语言或工具都可以通过HTTP连接
- 直接部署:直接安装在运行Home Assistant的Raspberry Pi上
- 无需MCP客户端:适用于任何HTTP客户端(curl、Postman、web浏览器)
- REST API标准:易于与现有系统和工作流程集成
- 独立操作:不需要MCP基础设施的独立服务
HTTP端点
HTTP服务器为Home Assistant提供完整的REST API接口:
GET /health-服务器健康检查和家庭助理连接状态GET /api/entities-列出所有实体(可选域过滤,如?domain=light)GET /api/entities/{entity_id}-获取特定实体状态和属性POST /api/services/call-呼叫总部助理服务(打开/关闭设备等)GET /api/history-通过时间范围过滤获取实体历史数据
使用案例:
- Web仪表板:为Home Assistant构建自定义web界面
- 移动应用:使用HTTP API创建本机移动应用程序
- 自动化脚本:使用任何编程语言实现家居自动化
- 第三方集成:将非MCP服务连接到家庭助理
- 开发测试:卷曲或Postman快速API测试
快速安装
自动安装:
curl -fsSL https://raw.githubusercontent.com/Jonathan97480/McpHomeAssistant/master/install.sh | bash手动安装:
git clone https://github.com/Jonathan97480/McpHomeAssistant.git
cd McpHomeAssistant
chmod +x install.sh
./install.sh快速启动HTTP服务器
# 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服务器在上运行 http://localhost:3002 默认情况下,并提供完整的REST API接口。
API调用示例:
# 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"}}'🎯 HTTP与MCP:什么时候使用哪个?
在以下情况下使用HTTP服务器:
- 🍓 直接安装在Raspberry Pi 3B上+
- 🌐 构建web应用程序或移动应用程序
- 🔧 与非MCP工具和服务集成
- 🚀 需要跨编程语言的通用兼容性
- 📊 创建自定义仪表板或监控系统
在以下情况下使用MCP服务器:
- 💻 与支持MCP的AI代理(Claude Desktop等)合作
- 🤖 需要基于工具的结构化交互
- 🔄 想要自动工具发现和模式验证
- 📝 更喜欢基于对话的设备控制
📁 项目结构
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🚀 安装
快速启动选项
🍓 Raspberry Pi安装(推荐)
直接安装在Raspberry Pi 3B+和家庭助理上:
# 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🎯 针对Raspberry Pi 3B+进行了优化:
- ✅ HTTP服务器设置:安装独立的HTTP服务器,便于AI集成
- ✅ 交互式配置:安装过程中提示输入Home Assistant令牌和URL
- ✅ 系统化服务:自动配置系统服务以自动启动
- ✅ 安全:适当的文件权限和服务隔离
- ✅ 端口3002:可从外部计算机访问的HTTP REST API
- ✅ 资源优化:适用于Pi 3B+硬件的轻量级部署
- ✅ Debian兼容:在Raspberry Pi OS(基于Debian)上测试
系统要求:
- Raspberry Pi 3B+或更新版本
- Raspberry Pi操作系统(建议使用Debian 11+)
- 在同一个Pi或网络上运行的家庭助手
- Python 3.9+(必要时自动安装)
- 至少512MB可用RAM
💻 桌面安装
对于开发或远程安装:
先决条件
- Python 3.8+
- 启用API的家庭助手
- 家庭助理访问令牌
服务器安装
cd homeassistant-mcp-server
pip install -e .配置
- 创建一个
.env文件:
HASS_URL=http://192.168.1.22:8123
HASS_TOKEN=your_token_here- 获取您的家庭助理令牌:
- 前往Home Assistant>个人资料>长期访问令牌 - 创建新令牌 - 复制到 .env 文件
Claude桌面配置
将此添加到您的Claude Desktop配置中(claude_desktop_config.json):
{
"mcpServers": {
"homeassistant": {
"command": "homeassistant-mcp-server",
"env": {
"HASS_URL": "http://192.168.1.22:8123",
"HASS_TOKEN": "your_token_here"
}
}
}
}📄 完整的配置文件可在 examples/claude_desktop_config.json
🤖 AI服务配置
克劳德桌面版
将此添加到您的Claude Desktop配置中(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工作室
在LM Studio中配置MCP:
- 打开LM工作室
- 前往“设置”>“MCP服务器”
- 添加新服务器:
- 名字: homeassistant - 命令: homeassistant-mcp-server - 环境变量:
HASS_URL=http://192.168.1.22:8123
HASS_TOKEN=your_token_hereContinue.dev(VS代码扩展)
添加到“继续”配置(.continue/config.json):
{
"mcpServers": {
"homeassistant": {
"command": "homeassistant-mcp-server",
"env": {
"HASS_URL": "http://192.168.1.22:8123",
"HASS_TOKEN": "your_token_here"
}
}
}
}光标IDE
添加到Cursor的AI配置:
- 打开光标IDE
- 前往“设置”>“AI”>“MCP服务器”
- 添加服务器配置:
{
"name": "homeassistant",
"command": "homeassistant-mcp-server",
"env": {
"HASS_URL": "http://192.168.1.22:8123",
"HASS_TOKEN": "your_token_here"
}
}Cline(VS代码扩展)
在临床设置中配置:
{
"mcpServers": {
"homeassistant": {
"command": "homeassistant-mcp-server",
"args": [],
"env": {
"HASS_URL": "http://192.168.1.22:8123",
"HASS_TOKEN": "your_token_here"
}
}
}
}LM工作室
LM Studio可以通过自定义HTTP功能使用服务器:
选项1:HTTP函数(推荐)
- 导入文件
configs/lm-studio-functions.json - 使用提示系统
configs/lm-studio-system-prompt.md - 确保HTTP服务器正在运行:
http://192.168.1.22:3002/health
配置快速:
{
"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}}"}
}
}
}📖 LM工作室指南 }
### OpenWebUI
For OpenWebUI MCP integration:
1. Install the MCP plugin
2. Configure server in settings:servers: homeassistant: command: homeassistant-mcp-server env: HASS_URL: "http://192.168.1.22:8123" HASS_TOKEN: "your_token_here"
### 自定义集成
对于其他MCP兼容服务,请使用以下标准格式:
{ "servers": { "homeassistant": { "command": "homeassistant-mcp-server", "env": { "HASS_URL": "http://192.168.1.22:8123", "HASS_TOKEN": "your_token_here" } } } }
**🔧 配置说明:**
- 替换 `your_token_here` 使用您实际的家庭助理令牌
- 如果您的家庭助理在其他地址上运行,请更新URL
- 某些服务可能需要可执行文件的完整路径
- 添加配置后重新启动AI服务
## 🧪 测试与验证
使用提供的脚本测试您的安装:
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
## 💬 用法
配置后,您可以询问Claude:
- “现在什么灯亮着?”
- “把客厅的灯都关掉”
- “显示传感器的温度”
- “今天的温度历史是多少?”
- “创建日落时自动开灯”
- “当能耗超过700千瓦时发出警报”
## 🛠️ 可用工具
MCP服务器公开 **8工具** 与家庭助理交互:
### 📋 **实体管理**
- **`get_entities`** :列出所有具有域筛选的实体
- **`get_entity_state`** :获取实体的详细状态
- **`get_history`** :给定时期的实体历史
### 🎮 **设备控制**
- **`call_service`** :调用服务来控制设备
- **`get_services`** :列出所有可用服务
### 🤖 **自动化** *新*
- **`create_automation`** :生成即用型YAML自动化
- **`list_automations`** :列出所有活动的自动化
- **`toggle_automation`** :启用/禁用自动化
## 💡 自动化示例
### ⚡ **能源监测**
- 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!"
### 🌅 **自动照明**
- alias: "Lights at sunset"
trigger: - platform: sun event: sunset offset: "-00:30:00" action: - service: light.turn_on target: area_id: living_room
### 📅 **预定通知**
- alias: "Morning notification"
trigger: - platform: time at: "08:00:00" action: - service: persistent_notification.create data: title: "🌅 Good Morning!" message: "Have a great day!"
## 📚 文档
- **[快速入门指南](docs/QUICKSTART.md)** -快速安装和配置
- **[建筑](docs/ARCHITECTURE.md)** -详细的技术文档
- **[测试](tests/README.md)** -测试脚本指南
- **[例子](examples/README.md)** -示例和配置
## 🔧 发展
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
## 许可证
麻省理工学院
______________________________________________________________________
# 法文版
强大的模型上下文协议(MCP)服务器,用于将Home Assistant与Claude Desktop等AI代理集成。
[🇬🇧 英文版本](#-home-assistant-mcp-server)
## ✨ 功能
- 🏠 **实体读取** :查看所有家庭助理设备的状态
- 🎮 **设备控制** :打开/关闭灯、开关等。
- 📊 **历史** :访问传感器和实体的历史记录
- 🔐 **安全认证** :使用Home Assistant访问令牌
- 🚀 **演出** :异步连接以实现最佳响应
- 🛠️ **服务** :呼叫任何家庭助理服务
- 🤖 **自动化** :生成智能YAML自动化
## 🌐 HTTP服务器模式
除了MCP协议之外,该服务器还可以作为独立的HTTP REST API服务器运行,非常适合:
- 🍓 **Raspberry Pi部署** 在家庭助理旁边
- 🔗 **应用程序web** 以及自定义集成
- 🚀 **架构微服务**
- 📱 **手机应用** 和第三方工具
- 🤖 **IA代理商** 不直接支持MCP协议
**为什么使用HTTP服务器模式?**
- **通用兼容性** :任何语言或工具都可以通过HTTP连接
- **直接部署** :使用Home Assistant直接安装在Raspberry Pi 3b+上
- **客户MCP要求** :适用于任何HTTP客户端(curl、邮递员、浏览器)
- **标准REST API** :易于与现有系统和工作流集成
- **自主操作** :不需要MCP基础设施的独立服务
## 📁 项目结构
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
## 🚀 安装
### 快速启动选项
#### 🍓 **安装Raspberry Pi(推荐)**
使用Home Assistant直接安装在Raspberry Pi 3b+上:
curl -sSL https://raw.githubusercontent.com/Jonathan97480/McpHomeAssistant/master/install.sh | bash
**🎯 针对Raspberry Pi 3b+进行了优化:**
- ✅ **HTTP服务器配置** :安装独立的HTTP服务器,以便轻松进行AI集成
- ✅ **配置交互** :在安装过程中请求令牌和URL Home Assistant
- ✅ **服务体系d** :自动配置系统服务以自动启动
- ✅ **安全** :适当的文件权限和服务隔离
- ✅ **端口3002** :可从外部机器访问的HTTP REST API
- ✅ **优化资源** :适用于PI 3B+硬件的轻量级部署
- ✅ **兼容Debian** :在Raspberry Pi OS(基于Debian)上测试
**系统要求:**
- 复盆子Pi 3b+或更高版本
- Raspberry Pi OS(建议使用Debian 11+)
- 在同一PI或网络上运行的家庭助理
- Python 3.9+(必要时自动安装)
- 至少512MB可用RAM
📖 **[指南完成Raspberry Pi](docs/RASPBERRY_PI_INSTALL.md)**
#### 💻 **安装局**
对于远程开发或安装:
### 先决条件
- Python 3.8+
- 启用API的家庭助手
- Home Assistant访问令牌
### 服务器安装
cd homeassistant-mcp-server pip install -e .
### 配置
1. 创建文件 `.env` :
HASS_URL=http://192.168.1.22:8123 HASS_TOKEN=votre_token_ici
2. 获取您的家庭助理代币:
- 转到主页助手>个人资料>长期访问令牌
- 创建新令牌
- 将其复制到文件中 `.env`
## 配置克劳德桌面
将此添加到您的Claude桌面配置(`claude_desktop_config.json`) :
{ "mcpServers": { "homeassistant": { "command": "homeassistant-mcp-server", "env": { "HASS_URL": "http://192.168.1.22:8123", "HASS_TOKEN": "votre_token_ici" } } } }
**📄 完整的配置文件可在 `examples/claude_desktop_config.json`**
## 🤖 d'IA服务配置
### 克劳德桌面版
将此添加到您的Claude桌面配置(`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工作室
在LM Studio中配置MCP:
1. 打开LM Studio
1. 转到设置>MCP服务器
1. 添加新服务器:
- **诺姆** : `homeassistant`
- **命令** : `homeassistant-mcp-server`
- **环境变量** :HASS_URL=http://192.168.1.22:8123 HASS_TOKEN=votre_token_ici
### Continue.dev(扩展VS代码)
添加到您的配置继续(`.continue/config.json`) :
{ "mcpServers": { "homeassistant": { "command": "homeassistant-mcp-server", "env": { "HASS_URL": "http://192.168.1.22:8123", "HASS_TOKEN": "votre_token_ici" } } } }
### 光标IDE
添加到光标AI配置:
1. 打开Cursor IDE
1. 转到设置>IA>MCP服务器
1. 添加服务器配置:{ "name": "homeassistant", "command": "homeassistant-mcp-server", "env": { "HASS_URL": "http://192.168.1.22:8123", "HASS_TOKEN": "votre_token_ici" } }
### Cline(扩展VS代码)
在Cline设置中配置:
{ "mcpServers": { "homeassistant": { "command": "homeassistant-mcp-server", "args": [], "env": { "HASS_URL": "http://192.168.1.22:8123", "HASS_TOKEN": "votre_token_ici" } } } }
### OpenWeb用户界面
对于OpenWebUI MCP集成:
1. 安装MCP插件
1. 在设置中配置服务器:servers: homeassistant: command: homeassistant-mcp-server env: HASS_URL: "http://192.168.1.22:8123" HASS_TOKEN: "votre_token_ici"
### 个性化集成
对于其他MCP兼容服务,请使用以下标准格式:
{ "servers": { "homeassistant": { "command": "homeassistant-mcp-server", "env": { "HASS_URL": "http://192.168.1.22:8123", "HASS_TOKEN": "votre_token_ici" } } } }
**🔧 配置注释:**
- 替换 `votre_token_ici` 通过您真正的代币家庭助理
- 如果您的家庭助理在其他地址工作,请更新URL
- 某些服务可能需要可执行文件的完整路径
- 添加配置后重新启动IA服务
## 🧪 测试与验证
使用提供的脚本测试安装:
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
## 💬 使用
配置后,您可以询问Claude:
- “我的灯亮着吗?”
- “关掉客厅里的所有灯”
- “告诉我传感器的温度”
- “我的温度传感器今天的历史是什么?”
- “创建在日落时打开灯光的自动化”
- “当我的能耗超过700 kWh时,生成警报”
## 🛠️ 可用工具
MCP服务器公开 **8工具** 要与家庭助理交互:
### 📋 **实体管理**
- **`get_entities`** :按域筛选的所有实体列表
- **`get_entity_state`** :获取实体的详细状态
- **`get_history`** :给定时间段内实体的历史记录
### 🎮 **设备控制**
- **`call_service`** :调用服务以控制设备
- **`get_services`** :列出所有可用服务
### 🤖 **自动化** *(新风格!)*
- **`create_automation`** :生成现成的YAML自动化
- **`list_automations`** :列出所有活动自动化
- **`toggle_automation`** :启用/禁用自动化
## 💡 自动化示例
### ⚡ **能源监测**
- 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 !"
### 🌅 **自动照明**
- 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
### 📅 **计划通知**
- alias: "Notification matinale"
trigger: - platform: time at: "08:00:00" action: - service: persistent_notification.create data: title: "🌅 Bonjour !" message: "Bonne journée !"
## � 项目结构
McpHomeAssistant/ ├── 📂 docs/ # 📚 Documentation complète │ ├── DEPLOYMENT_GUIDE.md # Guide de déploiement │ ├── 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 démarrage └── 📋 README.md # Ce fichier
## �📚 文档
### 🚀 安装和部署
- **[完整部署指南](docs/DEPLOYMENT_GUIDE.md)** -安装生产
- **[快速安装Raspberry Pi](docs/QUICK_INSTALL_RPI.md)** -导游快递
- **[详细安装Pi](docs/RASPBERRY_PI_INSTALL.md)** -完整的PI指南
### 🏗️ 建筑与发展
- **[系统架构](docs/ARCHITECTURE.md)** -文件编制技术
- **[API REST](docs/API_DOCUMENTATION.md)** -完整的API文档
- **[第3.4阶段](docs/PHASE_3_4_README.md)** -完整的web界面
### 🧪 测试与验证
- **[测试指南](tests/README.md)** -完整的测试套件
- **[使用示例](examples/README.md)** -实际例子
## 🔧 发展
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
## 许可证
麻省理工学院