家庭助手-mcp

Name: 家庭助手-mcp
Author: cronus42

作者：cronus424 星标更新：2025-07-19

安装使用来源：spider==github.com

项目介绍

Home Assistant MCP 服务器

一个全面的模型上下文协议（MCP）服务器，用于与 Home Assistant 集成。此服务器提供了 60 个工具 和资源，通过 REST API 与您的 Home Assistant 实例进行交互，实现完整的智能家居管理和自动化。

🚀 功能概览

在 9 大类别 中提供 60 个工具，以实现全面的 Home Assistant 管理：

🔧 核心操作（13 个工具）

实体状态管理：获取、设置、更新和删除实体状态
服务调用：执行 Home Assistant 服务并支持完整响应
实体搜索：高级搜索，按名称、域或状态过滤
事件处理：触发带有数据负载的自定义事件
模板渲染：使用实时数据渲染 Home Assistant 模板

🏠 区域及设备管理（8 个工具）

区域管理：创建、更新、删除区域/区域别名
设备注册：列出、配置和管理所有 Home Assistant 设备
实体组织：将实体分配到区域，批量区域操作
设备分配：在区域之间移动设备，启用/禁用设备

🖥️ 系统管理（6 个工具）

系统控制：安全地重启/停止 Home Assistant
健康监控：检查系统健康状况和组件状态
配置验证：在应用更改之前验证配置
监督集成：获取监督信息（Home Assistant OS）

🔌 集成管理（6 个工具）

集成生命周期：列出、启用、禁用、删除集成
集成故障排除：重新加载集成，获取详细信息
动态管理：编程方式管理集成配置

🔔 通知服务（3 个工具）

多渠道通知：通过移动应用发送持久通知
服务发现：列出所有可用的通知服务
通知管理：取消持久通知

📋 实体注册管理（4 个工具）

实体配置：更新实体名称、区域、启用/禁用状态
批量操作：启用/禁用多个实体
注册信息：获取详细的实体注册数据

🤖 自动化及场景管理（12 个工具）

自动化控制：创建、更新、删除、触发自动化
场景管理：激活场景，从当前状态创建新场景
自动化调试：获取执行跟踪和故障排除数据
生命周期管理：自动化全 CRUD 操作

📊 数据及历史记录（4 个工具）

历史数据：高级历史查询，带过滤选项
日志簿访问：获取事件历史和实体变化
错误日志：检索 Home Assistant 错误日志以进行调试

🎥 日历及媒体（4 个工具）

日历集成：列出日历并获取日期范围内的事件
摄像头支持：从摄像头实体获取图像（base64 编码）
意图处理：处理 Home Assistant 的语音/文本意图
实时事件：通过 SSE 订阅实时 Home Assistant 事件

安装

克隆此仓库：

git clone https://github.com/cronus42/homeassistant-mcp.git
cd homeassistant-mcp

运行安装脚本：

./setup.sh

获取您的 Home Assistant 长期访问令牌：
- 登录到您的 Home Assistant 网页界面
- 转到个人资料（点击左下角的用户名）
- 向下滚动到“长期访问令牌”
- 点击“创建令牌”
- 给它命名（例如，“MCP 服务器”）
- 复制令牌
配置设置：

cp .env.example .env
# 使用您的 Home Assistant URL 和令牌编辑 .env 文件

测试连接：

python tests/test_connection.py

使用 MCP 客户端

Warp 终端集成

运行安装脚本：

./setup.sh

配置 Warp 使用 MCP 服务器：

warp mcp add-server --config mcp_config.json

或者手动启动服务器：

./start_server.sh

Claude 桌面配置

添加到您的 Claude 桌面配置文件（macOS 上位于 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "homeassistant": {
      "command": "/path/to/homeassistant-mcp/start_server.sh",
      "env": {},
      "args": []
    }
  }
}

可用工具

`get_entity_state`

获取特定 Home Assistant 实体的当前状态。

{
  "entity_id": "light.living_room"
}

`call_service`

调用 Home Assistant 服务来控制设备。

{
  "domain": "light",
  "service": "turn_on",
 
  "entity_id": "light.living_room",
  "service_data": {
    "brightness": 255,
    "color_temp": 3000
  }
}

`search_entities`

按名称、域或状态搜索实体。

{
  "query": "temperature",
  "domain": "sensor"
}

`fire_event`

在 Home Assistant 中触发自定义事件。

{
  "event_type": "custom_automation_trigger",
  "event_data": {
    "source": "mcp_server",
    "action": "test"
  }
}

`get_history`

获取特定实体的历史数据。

{
  "entity_ids": ["sensor.temperature", "light.living_room"],
  "start_time": "2024-01-01T00:00:00Z"
}

新功能示例

区域管理

{
  "tool": "get_areas",
  "arguments": {}
}

创建和管理区域

{
  "tool": "create_area",
  "arguments": {
    "name": "家庭办公室",
    "aliases": ["办公室", "工作区"]
  }
}

设备管理

{
  "tool": "get_devices",
  "arguments": {}
}

系统健康检查

{
  "tool": "get_system_health",
  "arguments": {}
}

发送通知

{
  "tool": "send_notification",
  "arguments": {
    "message": "安全警报：前门打开",
    "title": "安全系统",
    "target": "mobile_app_phone"
  }
}

集成管理

{
  "tool": "get_integrations",
  "arguments": {}
}

测试

服务器包括全面的测试套件：

运行所有测试

# 测试工具定义和模式
python tests/test_mcp_tools.py

# 使用模拟测试工具处理器
python tests/test_tool_handlers.py

# 使用真实的 Home Assistant 测试（需要 HA_TOKEN）
python tests/test_new_features.py

# 测试基本连接
python tests/test_connection.py

测试结果

✅ 60/60 工具 正确定义
✅ 所有模式 验证通过
✅ 所有工具处理器 正常工作
✅ 新功能 100% 测试覆盖率

可用资源

homeassistant://states - 所有实体的当前状态
homeassistant://config - Home Assistant 配置
homeassistant://services - 可用服务
homeassistant://events - 可用事件类型

使用示例

打开灯光

{
  "tool": "call_service",
  "arguments": {
    "domain": "light",
    "service": "turn_on",
    "entity_id": "light.living_room"
  }
}

检查温度传感器

{
  "tool": "search_entities",
  "arguments": {
    "query": "temperature",
    "domain": "sensor"
  }
}

获取所有灯光的当前状态

{
  "tool": "search_entities",
  "arguments": {
    "query": "light",
    "domain": "light"
  }
}

安全性

安全存储您的 Home Assistant 令牌
使用环境变量进行配置
考虑 MCP 客户端和 Home Assistant 之间的网络安全
尽可能限制令牌权限

故障排除

连接问题

验证 Home Assistant URL 是否可访问
检查 Home Assistant API 是否已启用
确保令牌有效且具有适当的权限

认证错误

重新生成长期访问令牌
检查令牌格式（应为长字符串）
验证环境变量中是否设置了令牌

服务调用失败

检查实体 ID 是否存在于 Home Assistant 中
验证服务名称和参数
检查 Home Assistant 日志中的错误

贡献

欢迎提交问题和增强请求！