Hass-MCP

基本能力

产品定位

Hass-MCP 是一个连接 Home Assistant 与 AI 助手的桥梁，旨在通过自然语言交互实现智能家居的自动化控制和状态查询。

核心功能

• 实体管理：查询设备状态、控制设备、搜索实体
• 域摘要：获取实体类型的高级信息
• 自动化支持：列出和控制自动化
• 引导对话：使用提示完成常见任务（如创建自动化）
• 智能搜索：按名称、类型或状态查找实体
• 令牌效率：精简的 JSON 响应以最小化令牌使用

适用场景

• 通过自然语言控制智能家居设备
• 获取智能家居设备的状态摘要
• 创建和调试自动化
• 故障排除智能家居设备问题
• 优化智能家居设备的命名和布局

工具列表

• get_version：获取 Home Assistant 版本
• get_entity：获取特定实体的状态
• entity_action：对实体执行操作（如开关）
• list_entities：列出实体
• search_entities_tool：搜索匹配查询的实体
• domain_summary_tool：获取域的实体摘要
• list_automations：列出所有自动化
• call_service_tool：调用任何 Home Assistant 服务
• restart_ha：重启 Home Assistant
• get_history：获取实体的状态历史
• get_error_log：获取 Home Assistant 错误日志

常见问题解答

• 如何设置 HA_URL：如果 Home Assistant 运行在同一台机器上，使用 http://host.docker.internal:8123；如果在另一台机器上，使用实际的 IP 或主机名。
• 如何获取长寿命访问令牌：在 Home Assistant 的用户配置文件中创建长寿命访问令牌。

使用教程

使用依赖

• Home Assistant 实例及长寿命访问令牌
• Docker 或 Python 3.13+ 和 uv

安装教程

Docker 安装（推荐）

1. 拉取 Docker 镜像： bash docker pull voska/hass-mcp:latest
2. 将 MCP 服务器添加到 Claude Desktop：
3. 打开 Claude Desktop 并进入设置
4. 导航到开发者 > 编辑配置
5. 在 claude_desktop_config.json 文件中添加配置
6. 替换 YOUR_LONG_LIVED_TOKEN 为您的实际令牌
7. 更新 HA_URL 以匹配您的 Home Assistant 实例地址
8. 保存文件并重启 Claude Desktop

调试方式

• 使用 get_entity 工具查询设备状态以验证连接
• 使用 list_entities 工具列出所有实体以确认权限
• 检查 Docker 日志以查看运行错误

许可证

该项目遵循 MIT 开源许可条款，请参阅 MIT 了解完整条款。