AI导哈

智能家居控制服务器

Home Assistant MCP Server 是一个专为Home Assistant设计的模型上下文协议服务器，用于控制和监控智能家居设备，管理自动化场景，并通过Docker容器提供高效部署。

  • by amattas
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 amattas/homeassistant-mcp

使用说明

家庭助理MCP服务器

用于家庭助理设备控制和监控的专用模型上下文协议（MCP）服务器。此基于Docker的服务器使Claude Desktop和其他MCP客户端能够与您的家庭助理实例交互，以控制智能家居设备、监控传感器和管理自动化。

特性

  • 设备控制：控制灯、开关、盖子、锁和气候设备
  • WebSocket支持：区域和实体的WebSocket回退高级连接
  • 传感器监测：组织和查询9个类别的345+个传感器
  • 区域管理：通过WebSocket API访问24个以上的家庭区域
  • 场景与自动化：触发场景并执行自动化
  • 实体查询：查询1500多个实体的状态
  • 服务执行：致电任何家庭助理服务
  • 能源监测：跟踪能源使用和消耗情况
  • 安全检查：监控锁、门和安全传感器
  • Redis缓存：可选缓存以提高性能
  • Docker支持：使用Docker和Docker Compose轻松部署

先决条件

  • 码头工人 和 Docker Compose （用于集装箱化部署）
  • 家庭助手：正在运行的Home Assistant实例（本地或远程）
  • 长效访问令牌：根据您的家庭助理配置文件生成
  • 网络接入：服务器必须能够访问您的家庭助理实例
  • 克劳德桌面版 （可选）：用于MCP客户端集成

快速开始

1.获取家庭助理访问令牌

  1. 打开您的家庭助理实例
  2. 点击您的个人资料（左下角）
  3. 滚动到“长期访问令牌”
  4. 点击“创建令牌”
  5. 为其命名（例如，“MCP服务器”）
  6. 立即复制生成的令牌（不会再次显示）

2.克隆和配置

cd homeassistant-mcp
cp .env.example .env.local

编辑 .env.local 并添加您的家庭助理详细信息：

# Home Assistant URL (include http:// or https://)
HA_URL=http://homeassistant.local:8123

# Long-lived access token
HA_TOKEN=your-long-lived-access-token-here

# SSL verification (set to false for self-signed certificates)
HA_VERIFY_SSL=true

# Debug mode
DEBUG=false

# Optional Redis caching
REDIS_HOST=
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_USE_SSL=false

3.使用Docker Compose运行

docker-compose up --build

服务器将以stdio模式启动，准备接受MCP连接。

4.连接到克劳德桌面

将此配置添加到您的Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "homeassistant": {
      "command": "docker",
      "args": ["compose", "-f", "/path/to/homeassistant-mcp/docker-compose.yml", "run", "--rm", "homeassistant-mcp"]
    }
  }
}

重新启动Claude Desktop以激活服务器。

配置

环境变量

变量 必填 默认 描述
HA_URL 是 - 家庭助理URL（例如。，http://homeassistant.local:8123)
HA_TOKEN 是 - 长期访问令牌
HA_VERIFY_SSL 没有 true 验证SSL证书（对于自签名设置为false）
DEBUG 没有 false 启用调试日志记录
REDIS_HOST 无 - Redis服务器主机名（用于缓存）
REDIS_PORT 没有 6379 Redis服务器端口
REDIS_PASSWORD 无 - Redis密码
REDIS_USE_SSL 没有 false 使用SSL进行Redis连接

可用的MCP工具

家庭助理MCP服务器提供以下工具：

设备控制

灯：

  • turn_on_light -打开具有可选亮度的灯
  • turn_off_light -关灯
  • toggle_light -切换灯光状态
  • set_light_brightness -设置亮度（0-100%）

开关：

  • turn_on_switch -打开开关
  • turn_off_switch -关闭开关
  • toggle_switch -切换开关状态

气候：

  • set_temperature -设定目标温度
  • set_hvac_mode -设置暖通空调模式（加热、制冷、自动、关闭）
  • turn_on_climate -打开空调设备
  • turn_off_climate -关闭空调设备

盖子（百叶窗/遮光罩）：

  • open_cover -打开盖子
  • close_cover -盖上盖子
  • stop_cover -停止盖子移动
  • set_cover_position -设置盖子位置（0-100%）

锁：

  • lock_door -锁上门
  • unlock_door -打开车门

场景与自动化

  • activate_scene -激活场景
  • trigger_automation -触发自动化
  • run_script -执行脚本

实体和州查询

  • get_entity_state -获取特定实体的状态
  • get_all_entities -列出所有实体
  • get_entities_by_area -获取某个区域中的实体
  • get_entities_by_domain -按类型（灯、开关等）获取实体

区域管理

  • get_all_areas -列出所有区域
  • get_area_devices -在某个区域获取设备
  • get_area_entities -获取某个区域中的实体

传感器监测

  • get_all_sensors -获取所有传感器状态
  • get_sensors_by_category -按类别（天气、暖通空调、能源等）获取传感器
  • get_sensor_value -获取特定的传感器值

传感器类别：

  • 天气（温度、湿度、压力）
  • 池（温度、化学水平）
  • 空气质量（PM2.5、挥发性有机化合物、二氧化碳）
  • 暖通空调（气候控制）
  • 能源（功率、消耗）
  • 安全（门、锁、运动）
  • 媒体（电视、音频状态）
  • 网络（连接性）
  • 系统（电池、诊断）

服务执行

  • call_service -呼叫任何家庭助理服务
  • execute_service -使用参数执行服务

服务器管理

  • get_server_status -检查服务器运行状况
  • get_server_config -查看服务器配置
  • test_connection -测试家庭助理连接
  • get_cache_stats -查看缓存性能指标
  • clear_cache -清除缓存数据
  • get_cache_info -查看Redis服务器信息

本地开发

没有Docker

  1. 创建虚拟环境：
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
  1. 安装依赖项：
pip install -r requirements.txt
  1. 设置环境变量：
export HA_URL=http://homeassistant.local:8123
export HA_TOKEN=your-token
  1. 运行服务器：
python server.py

使用Docker

构建并运行：

docker build -t homeassistant-mcp .
docker run -e HA_URL=http://... -e HA_TOKEN=... homeassistant-mcp

测试

测试服务器状态

您可以通过Claude Desktop连接并询问以下问题来测试服务器：

“我的家庭助理服务器的状态如何？”

测试设备控制

“打开客厅的灯” “将卧室温度设置为72度” “锁上前门”

测试传感器查询

“现在的温度是多少？” “显示所有天气传感器” “我的能源消耗是多少？”

测试自动化

“激活电影夜景” “运行早安自动化”

故障排除

“未配置家庭助理”

解决方案：确保两者 HA_URL 和 HA_TOKEN 设置在您的 .env.local 文件。

连接测试失败

解决方案:

  • 验证 HA_URL 正确且可从Docker容器访问
  • 检查家庭助理是否正在运行
  • 确保访问令牌有效
  • 对于具有自签名证书的HTTPS，请设置 HA_VERIFY_SSL=false

SSL证书错误

解决方案:

  • 如果使用自签名证书，请设置 HA_VERIFY_SSL=false
  • 考虑使用HTTP进行本地网络连接
  • 如果使用HTTPS，请确保证书有效

未找到实体

解决方案:

  • 使用 get_all_entities 列出可用实体
  • 检查实体ID格式（例如。， light.living_room，不 living_room)
  • 验证家庭助理中是否存在该实体

WebSocket连接问题

解决方案:

  • 服务器会自动回退到WebSocket进行某些操作
  • 检查家庭助理日志中的WebSocket错误
  • 确保WebSocket端口（通常为8123）可访问

建筑

家庭助理MCP服务器遵循以下架构：

Claude Desktop
     ↓ (stdio)
Docker Container
     ↓
MCP Server (FastMCP)
     ↓
Home Assistant Client
     ├─ REST API (primary)
     ├─ WebSocket API (fallback/advanced)
     └─ SSE (Server-Sent Events)
     ↓
Home Assistant Instance
     ├─ Entities (1,500+)
     ├─ Areas (24+)
     ├─ Sensors (345+)
     └─ Services

可选的Redis缓存层通过缓存实体状态来提高性能。

高级功能

WebSocket区域支持

当REST API不足时，服务器使用WebSocket API访问区域信息。这提供了：

  • 实时区域更新
  • 访问24+家庭区域
  • 每个区域的全面设备列表

传感器分类

传感器自动分为9组：

  1. 天气：温度、湿度、压力传感器
  2. 池：游泳池温度、化学传感器
  3. 空气质量：PM2.5、VOC、CO2传感器
  4. 暖通空调：气候和加热传感器
  5. 能量：功率和功耗传感器
  6. 安全：门、锁、运动传感器
  7. 媒体：电视和音频状态传感器
  8. 网络：连接传感器
  9. 系统：蓄电池和诊断传感器

基于百分比的亮度

灯光亮度以百分比（0-100%）处理，以提高可用性，自动转换为家庭助理的0-255范围。

安全说明

  • 永远不要承诺你的 .env.local 版本控制的文件或访问令牌
  • 使用环境特定 .env 文件
  • 考虑Docker容器的网络隔离
  • 长期使用的访问令牌应定期轮换
  • 使用HTTPS进行远程家庭助理连接
  • 令牌永远不会通过MCP工具响应暴露

演出

  • 自动缓存：缓存实体状态以减少API调用
  • WebSocket回退：通过WebSocket实现高效的实时更新
  • Redis支持：用于多实例部署的可选Redis缓存
  • 连接池：重用HTTP连接以获得更好的性能

实体ID格式

Home Assistant使用以域为前缀的实体ID：

  • 灯： light.living_room_lamp
  • 开关： switch.bedroom_fan
  • 传感器： sensor.outdoor_temperature
  • 气候： climate.thermostat
  • 盖子： cover.bedroom_blinds
  • 锁： lock.front_door

许可证

本项目按原样提供供个人使用。

支持

有关Home Assistant文档，请访问：https://www.home-assistant.io/docs/

相关 MCP