hass-mcp

🚀 Hass-MCP 说明文档

Hass-MCP 是一款专为 Home Assistant 集成打造的 Model Context Protocol (MCP) 服务器，它能助力 Claude 等大语言模型（LLMs）与 Home Assistant 实现交互，为智能家居控制带来更多可能。

🚀 快速开始

Hass-MCP 架起了 AI 助手（如 Claude）与 Home Assistant 实例之间的桥梁，让 AI 助手能够直接与您的智能家居系统交互，实现以下实用功能：

• 查询设备和传感器的状态
• 控制灯、开关和其他实体
• 获取智能家居的概要信息
• 排查自动化和实体问题
• 搜索特定实体
• 创建常见任务的引导对话

📷 截图

✨ 主要特性

• 实体管理：获取状态、控制设备以及搜索实体
• 版本获取工具：获取 Home Assistant 的版本信息
• 实体操作工具：对实体执行操作（如打开、关闭、切换）
• 实体列表工具：获取所有实体的列表，支持按领域过滤和搜索
• 自动化列表工具：获取所有自动化的列表
• 服务调用工具：调用 Home Assistant 的任意服务
• 重启 Home Assistant 工具：重启 Home Assistant 实例
• 状态历史记录工具：获取某个实体的状态历史记录
• 错误日志获取工具：获取 Home Assistant 的错误日志

📚 详细文档

引导对话提示

Hass-MCP 提供了丰富的引导对话提示，帮助用户更好地使用 Home Assistant：

• create_automation：根据触发类型指导创建 Home Assistant 自动化
• debug_automation：帮助故障排除未正常工作的自动化
• troubleshoot_entity：诊断实体问题
• routine_optimizer：分析使用模式并基于实际行为提出优化例程建议
• automation_health_check：审查所有自动化，发现冲突、冗余或改进机会
• entity_naming_consistency：审核实体名称并建议命名标准化改进
• dashboard_layout_generator：根据用户偏好和使用模式生成优化的仪表板

可用资源端点

Hass-MCP 提供了一系列资源端点，方便用户获取各种信息：

• hass://entities/{entity_id}：获取某个特定实体的状态
• hass://entities/{entity_id}/detailed：获取某个实体的详细信息，包括所有属性
• hass://entities：列出 Home Assistant 所有实体，按领域分组
• hass://entities/domain/{domain}：获取某个领域的所有实体列表
• hass://search/{query}/{limit}：搜索与查询匹配的实体，并自定义结果限制

💻 使用示例

基础用法

uv run pytest tests/

📄 许可证

本项目采用 MIT License。