家庭助手-MCP

Name: 家庭助手-MCP
Author: voska

作者：voska234 星标更新：2025-08-06

安装使用来源：spider==github.com

项目介绍

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（Mac/Windows上的Docker Desktop）
- 如果在另一台机器上运行Home Assistant：使用实际的IP地址或主机名
f. 保存文件并重启Claude Desktop
"Hass-MCP"工具现在应该出现在您的Claude Desktop工具菜单中

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

uv/uvx

在您的系统上安装uv。
将MCP服务器添加到Claude Desktop：

a. 打开Claude Desktop并进入设置 b. 导航至开发者 > 编辑配置 c. 在您的claude_desktop_config.json文件中添加以下配置：
```
{
  "mcpServers": {
    "hass-mcp": {
      "command": "uvx",
      "args": ["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（Mac/Windows上的Docker Desktop）
- 如果在另一台机器上运行Home Assistant：使用实际的IP地址或主机名
f. 保存文件并重启Claude Desktop
"Hass-MCP"工具现在应该出现在您的Claude Desktop工具菜单中

其他MCP客户端

Cursor

转到Cursor设置 > MCP > 添加新MCP服务器
填写表单：
- 名称：Hass-MCP
- 类型：命令
- 命令：
```
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实例地址。

使用示例

这里是一些您可以与Claude一起使用的提示示例，一旦设置了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许可证