AI导哈

智能家居管理服务器

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

  • by cronus42
  • Python
  • 本地部署
  • 5 星标
  • 更新于
在 GitHub 查看 cronus42/homeassistant-mcp

使用说明

家庭助理MCP服务器

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

🚀 功能概述

总共60个工具 横跨 9大类 全面的家庭助理管理：

🔧 核心业务 （13个工具）

  • 实体国家管理：获取、设置、更新和删除实体状态
  • 服务呼叫：执行家庭助理服务，提供全面的响应支持
  • 实体搜索：高级搜索，可按名称、域或州进行筛选
  • 事件处理：使用数据有效载荷触发自定义事件
  • 模板渲染：使用实时数据渲染家庭助手模板

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

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

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

  • 系统控制：安全地重新启动/停止家庭助理
  • 健康监测：检查系统运行状况和组件状态
  • 配置验证：在应用更改之前验证配置
  • 主管集成：获取主管信息（家庭助理操作系统）

🔌 整合管理 （6个工具）

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

🔔 通知服务 （3个工具）

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

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

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

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

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

📊 数据和历史 （4个工具）

  • 历史数据：具有过滤选项的高级历史查询
  • 日志访问：获取事件历史记录和实体更改
  • 错误记录：检索家庭助理错误日志以进行调试

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

  • 日历集成：列出日历并获取具有日期范围的事件
  • 摄像机支架：从相机实体获取图像（base64编码）
  • 意图处理：处理家庭助理语音/文本意图
  • 实时事件：通过SSE订阅实时家庭助理活动

安装

  1. 克隆此存储库：
git clone https://github.com/cronus42/homeassistant-mcp.git
cd homeassistant-mcp
  1. 运行安装脚本：
./setup.sh

  1. 获取您的家庭助理长期访问令牌：

    • 登录到您的家庭助理web界面
    • 转到个人资料（单击左下角的用户名）
    • 向下滚动到“长期访问令牌”
    • 点击“创建令牌”
    • 为其命名（例如，“MCP服务器”）
    • 复制令牌

  2. 配置您的设置：

cp .env.example .env
# Edit .env with your Home Assistant URL and token
  1. 测试连接：
python tests/test_connection.py

与MCP客户端一起使用

曲速终端集成

  1. 运行安装脚本：
./setup.sh
  1. 配置Warp以使用MCP服务器：
warp mcp add-server --config mcp_config.json

或者手动启动服务器：

./start_server.sh

Claude桌面配置

添加到您的Claude Desktop配置文件(~/Library/Application Support/Claude/claude_desktop_config.json 在 macOS 上：

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

可用工具

get_entity_state

获取特定家庭助理实体的当前状态。

{
  "entity_id": "light.living_room"
}

call_service

呼叫家庭助理服务来控制设备。

{
  "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": "Home Office",
    "aliases": ["office", "workspace"]
  }
}

设备管理

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

系统健康检查

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

发送通知

{
  "tool": "send_notification",
  "arguments": {
    "message": "Security Alert: Front door opened",
    "title": "Security System",
    "target": "mobile_app_phone"
  }
}

整合管理

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

测试

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

运行所有测试

# Test tool definitions and schemas
python tests/test_mcp_tools.py

# Test tool handlers with mocking
python tests/test_tool_handlers.py

# Test with real Home Assistant (requires HA_TOKEN)
python tests/test_new_features.py

# Test basic connection
python tests/test_connection.py

测试结果

  • ✅ 60/60工具 正确定义
  • ✅ 所有架构 已验证
  • ✅ 所有工具处理程序 正确工作
  • ✅ 100%测试覆盖率 对于新功能

可用资源

  • homeassistant://states -所有实体的当前状态
  • homeassistant://config -家庭助理配置
  • 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"
  }
}

安全

  • 安全地存储您的家庭助理令牌
  • 使用环境变量进行配置
  • 考虑MCP客户端和家庭助理之间的网络安全
  • 如果可能，限制令牌权限

故障排除

连接问题

  • 验证家庭助理URL是否可访问
  • 检查是否启用了Home Assistant API
  • 确保令牌有效并具有适当的权限

身份验证错误

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

服务呼叫失败

  • 检查家庭助理中是否存在实体ID
  • 验证服务名称和参数
  • 检查家庭助理日志是否有错误

贡献

请随时提交问题和增强请求！

相关 MCP