Hass-MCP

一个用于 Home Assistant 与 Claude 及其他 LLMs 集成的 Model Context Protocol (MCP) 服务器。

概览

Hass-MCP 使像 Claude 这样的 AI 助手能够直接与您的 Home Assistant 实例交互，允许它们：

查询设备和传感器的状态
控制灯光、开关和其他实体
获取智能家居的摘要
对自动化和实体进行故障排除
搜索特定实体
为常见任务创建引导对话

屏幕截图

特性

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

安装

先决条件

带有长期访问令牌的 Home Assistant 实例
以下之一：
- Docker（推荐）
- Python 3.13+ 和 uv

使用 Claude Desktop 设置

Docker 安装（推荐）

拉取 Docker 镜像：
```
docker pull voska/hass-mcp:latest
```
将 MCP 服务器添加到 Claude Desktop 中：

a. 打开 Claude Desktop 并进入设置
b. 导航到开发者 > 编辑配置
c. 在您的 claude_desktop_config.json 文件中添加以下配置：
```
{
  "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"
      }
    }
  }
}
```
d. 将 YOUR_LONG_LIVED_TOKEN 替换为您实际的 Home Assistant 长期访问令牌
e. 更新 HA_URL：
- 如果在相同机器上运行 Home Assistant：使用 http://host.docker.internal:8123（Docker Desktop for Mac/Windows）
- 如果在另一台机器上运行 Home Assistant：使用实际的 IP 地址或主机名
f. 保存文件并重启 Claude Desktop
现在，“Hass-MCP”工具应该出现在您的 Claude Desktop 工具菜单中

注意: 如果你在同一台机器上使用 Docker 运行 Home Assistant，你可能需要在 Docker 参数中添加 --network host 以便容器能够访问 Home Assistant。或者，你可以使用你的机器的 IP 地址代替 host.docker.internal。

其他 MCP 客户端

Cursor

转到 Cursor 设置 > MCP > 添加新的 MCP 服务器
填写表单：
- 名称: Hass-MCP
- 类型: command
- 命令:
```
docker run -i --rm -e HA_URL=http://homeassistant.local:8123 -e HA_TOKEN=YOUR_LONG_LIVED_TOKEN voska/hass-mcp
```
- 将 YOUR_LONG_LIVED_TOKEN 替换为你的实际 Home Assistant 令牌
- 更新 HA_URL 以匹配你的 Home Assistant 实例地址
点击“添加”保存

Claude Code (CLI)

要与 Claude Code CLI 一起使用，你可以直接使用 mcp add 命令添加 MCP 服务器：

使用 Docker（推荐）：

claude mcp add hass-mcp -e HA_URL=http://homeassistant.local:8123 -e HA_TOKEN=YOUR_LONG_LIVED_TOKEN -- docker run -i --rm -e HA_URL -e HA_TOKEN voska/hass-mcp

将 YOUR_LONG_LIVED_TOKEN 替换为你的实际 Home Assistant 令牌，并更新 HA_URL 以匹配你的 Home Assistant 实例地址。

使用示例

以下是一些设置好 Hass-MCP 后可以使用的提示示例：

"我的客厅灯现在的状态是什么？"
"关闭厨房里所有的灯"
"列出所有包含温度数据的传感器"
"给我一个关于气候实体的摘要"
"创建一个在日落时打开灯光的自动化"
"帮我排查为什么我的卧室运动传感器自动化不起作用"
"搜索与我的客厅相关的实体"

可用工具

Hass-MCP 提供了几个用于与 Home Assistant 交互的工具：

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

引导对话的提示

Hass-MCP 包含了几个用于引导对话的提示：

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