AI导哈

智能家居控制服务器

一个Rust编写的轻量级服务器，连接Claude Code（或任何MCP客户端）到Home Assistant和Zigbee2MQTT，提供智能家居设备的状态查询和控制功能。

  • by Saturate
  • Rust
  • 本地部署
  • 更新于
在 GitHub 查看 Saturate/smarthome-mcp

使用说明

智能家居mcp

连接Claude Code（或任何MCP客户端）的MCP服务器 家庭助手 和 ZigBee 2MQTT.用Rust编写，作为15MB以下的单个静态二进制文件发布。

后端

家庭助理（REST API）

工具 范围 描述
ha_entity.get_state ha:read 获取任何实体的状态
ha_entity.list ha:read 按域列出实体，按设备类或状态筛选
ha_entity.search ha:read 按关键字搜索实体
ha_area.list ha:read 列出所有已配置的区域
ha_area.get_status ha:read 获取一个区域中的所有实体状态
ha_todo.get_items ha:read 从待办事项列表中获取项目
ha_light.turn_on ha:control 启用灯光实体
ha_light.turn_off ha:control 关闭灯光实体
ha_light.set_brightness ha:control 设置亮度（0-255）
ha_light.turn_on_in_area ha:control 打开一个区域的所有灯
ha_light.turn_off_in_area ha:control 关闭一个区域的所有灯
ha_todo.add_item ha:control 将项目添加到待办事项列表
ha_todo.update_item ha:control 重命名或更改todo项目的状态
ha_todo.remove_item ha:control 从待办事项列表中删除项目
ha_service.call ha:control 适用于任何HA服务的通用逃生口

ZigBee 2MQTT（MQTT）

工具 范围 描述
z2m_device.list z2m:read 列出所有Zigbee设备及其暴露的功能
z2m_device.get_state z2m:read 获取设备的当前状态（包括可用性）
z2m_group.list z2m:read 列出所有Z2M组
z2m_bridge.info z2m:read 获取网桥信息（协调器、版本、网络）
z2m_device.set z2m:control 设置设备状态；根据设备的暴露情况进行验证
z2m_device.rename z2m:control 重命名设备
z2m_group.add z2m:control 创建Z2M组
z2m_bridge.permit_join z2m:control 启用/禁用许可加入
z2m_bridge.networkmap z2m:control 请求网络地图

z2m_device.set 根据每个设备的有效载荷进行验证 exposes 发送前的定义。未知字段和超出范围的值将被拒绝，并显示一个有用的错误。

设置

先决条件

  • 一个具有 长期访问令牌 （用于HA后端）
  • 具有MQTT代理访问权限的Zigbee2MQTT实例（用于Z2M后端）
  • 任一后端都是可选的；配置一个或两个

使用Docker运行

docker run -d \
  -p 3000:3000 \
  -e HA_URL=http://homeassistant.local:8123 \
  -e HA_TOKEN=your_token \
  -e Z2M_MQTT_HOST=mqtt://localhost:1883 \
  ghcr.io/alkj/smarthome-mcp:latest

或者使用配置文件：

docker run -d \
  -p 3000:3000 \
  -v ./config.toml:/config.toml \
  -e CONFIG_FILE=/config.toml \
  ghcr.io/alkj/smarthome-mcp:latest

在本地运行

# With env vars
HA_URL=http://homeassistant.local:8123 HA_TOKEN=your_token cargo run

# Or with config file
CONFIG_FILE=config.toml cargo run

从源代码构建

cargo build --release

Claude代码配置

增添 .mcp.json 在您的项目中（或 ~/.claude/settings.json 全球）：

{
  "mcpServers": {
    "smarthome": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

配置

通过环境变量、TOML配置文件或两者进行配置。环境变量会覆盖TOML值。

环境变量

# Home Assistant (omit to disable)
HA_URL=http://homeassistant.local:8123
HA_TOKEN=your_long_lived_access_token

# Zigbee2MQTT (omit to disable)
Z2M_MQTT_HOST=mqtt://localhost:1883
Z2M_MQTT_USER=              # optional
Z2M_MQTT_PASS=              # optional
Z2M_BASE_TOPIC=zigbee2mqtt  # default: zigbee2mqtt

# Server
PORT=3000                   # default: 3000
CONFIG_FILE=config.toml     # optional path to TOML config

TOML配置

看 config.example.toml 关于auth规则的完整示例。

认证

身份验证是可选的。没有a [auth] 部分，允许所有请求（仅本地设置的打开模式）。

三种策略，按顺序评估（第一场比赛获胜）：

  1. IP白名单 -为来自配置的CIDR范围的请求授予范围，不需要令牌
  2. 静态令牌 -配置中定义的承载令牌，每个令牌都有自己的作用域
  3. 代理 -根据HA的REST API或MQTT代理验证承载令牌

作用域

范围 访问
ha:read 实体/区域状态查询、列表、搜索
ha:control 灯光控制、待办事项管理、， ha_service.call
z2m:read 设备/组列表、状态查询、网桥信息
z2m:control 设备设置/重命名、组管理、允许加入
* 所有范围

示例：授予您的本地网络完全访问权限，外部客户端只读：

[auth]

[[auth.whitelist]]
cidrs = ["192.168.0.0/16", "10.0.0.0/8"]
scopes = ["*"]

[[auth.tokens]]
token = "readonly-external-token"
scopes = ["ha:read", "z2m:read"]

健康终点

GET /health 返回后端状态：

{
  "status": "ok",
  "backends": {
    "ha": { "status": "ok" },
    "z2m": { "status": "ok" }
  }
}

status 是 "ok" 当所有配置的后端都可访问时， "degraded" 当至少一个故障时， "unavailable" 当一切都下来的时候。即使后端无法访问，服务器也会启动并处理请求。

建筑学

  • MCP传输: rmcp 通过axum使用可流式传输的HTTP
  • HA客户端：reqwest 10秒暂停
  • Z2M客户端：保留内存设备缓存的rumqttc bridge/devices 主题
  • 码头工人：多拱形（amd64+arm64）静态musl二进制文件

备注

  • HA后端使用HA的 模板API 用于区域/设备发现，因为REST API没有直接区域端点。
  • Z2M设备有效载荷根据设备的 exposes 定义。使用 z2m_device.list 查看每个设备接受什么。
  • Z2M MQTT客户端在连接丢失时会自动重新连接。

相关 MCP