家庭助手MCP

你是否曾经希望AI能够直接控制你的智能家居设备，查询状态、开关灯光、执行自动化？今天要介绍的开源项目家庭助手MCP，正是为了实现这个目标而设计的。它是一个MCP服务器，使像Claude这样的人工智能助手能够直接与Home Assistant交互，从而查询设备状态、控制智能家居实体并执行自动化任务。

项目基本信息

一、项目介绍

家庭助手MCP是一个让AI能够与Home Assistant交互的MCP服务器。它支持查询设备状态、控制灯光和开关、获取智能家居摘要、对自动化进行故障排除、搜索特定实体等功能。

这个服务器提供了以下工具：

• 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错误日志

二、核心优势

智能家居控制

通过AI控制灯光、开关等设备。

自动化支持

列出并控制自动化任务。

故障排除

帮助排查自动化问题。

令牌效率

简洁的JSON响应，最小化令牌使用。

引导对话

提供创建自动化的引导提示。

三、适用场景

语音控制家居

通过AI语音控制智能设备。

自动化创建

AI辅助创建自动化规则。

设备故障排查

AI帮助诊断实体问题。

节能优化

分析使用模式，优化例行程序。

四、安装教程

系统要求

安装步骤

第一步：获取Home Assistant令牌

1. 登录Home Assistant
2. 进入用户资料
3. 创建长期访问令牌

第二步：Docker安装（推荐）

拉取镜像：

docker pull voska/hass-mcp:latest

第三步：配置Claude Desktop

找到配置文件，添加：

{
  "mcpServers": {
    "hass-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "HA_URL",
        "-e",
        "HA_TOKEN",
        "voska/hass-mcp"
      ],
      "env": {
        "HA_URL": "http://homeassistant.local:8123",
        "HA_TOKEN": "YOUR_LONG_LIVED_TOKEN"
      }
    }
  }
}

注意：

• 同一机器运行HA：使用http://host.docker.internal:8123
• 不同机器：使用实际IP地址

第四步：Cursor配置

名称：Hass-MCP
类型：command
命令：docker run -i --rm -e HA_URL=http://homeassistant.local:8123 -e HA_TOKEN=YOUR_TOKEN voska/hass-mcp

五、使用示例

示例1：查询设备状态

用户指令：“我的客厅灯现在的状态是什么？”

示例2：控制设备

用户指令：“关闭厨房里所有的灯”

示例3：搜索实体

用户指令：“搜索与我的客厅相关的实体”

示例4：创建自动化引导

AI可以使用create_automation提示来引导创建自动化。

示例5：调试自动化

用户指令：“帮我排查为什么我的卧室运动传感器自动化不起作用”

六、资源端点

• hass://entities/{entity_id}：获取实体状态
• hass://entities/{entity_id}/detailed：获取详细实体信息
• hass://entities：列出所有实体（按域分组）
• hass://entities/domain/{domain}：获取特定域实体
• hass://search/{query}/{limit}：搜索实体

七、常见问题

问题1：Docker容器无法连接HA

解决方案：使用--network host或使用机器IP地址。

问题2：令牌无效

解决方案：重新生成长期访问令牌。

问题3：实体找不到

解决方案：检查实体ID是否正确。

问题4：自动化不工作

解决方案：使用debug_automation提示。

问题5：API版本问题

解决方案：确保Home Assistant版本兼容。

八、总结

家庭助手MCP是一个让AI能够控制Home Assistant智能家居的MCP服务器，支持设备控制、自动化管理和故障排除。

这个项目的最大价值在于：

1. 智能家居控制：通过AI控制设备
2. 自动化支持：创建和管理自动化
3. 故障排除：诊断实体问题
4. 令牌效率：简洁响应
5. MIT许可证：可自由使用

如果你使用Home Assistant，并希望用AI控制智能家居，家庭助手MCP是一个非常实用的工具。