mijia-home-mcp

米家全屋状态快照 MCP server —— 默认只读,一次调用看清全家。

让 Claude / Cursor 等 MCP 客户端安全地"看家":一个 get_home_snapshot 工具并发拉取全屋设备状态,返回 家 → 房间 → 设备 → 语义化状态 的结构化结果;get_home_changes 回答"上次以来家里变了什么"。控制能力(开关/属性/场景)默认关闭,需要显式开启并受白名单与危险设备策略约束。

基于 Do1e/mijia-api(GPL-3.0),与其共用登录凭证(扫码一次约保活一个月)。

为什么不是又一个米家 MCP

Related MCP server: xiaomi-device-control

快速开始

无需 clone,uvx 直接从 GitHub 运行。

1. 扫码登录(终端会打印二维码,用米家 App 扫描,凭证约一个月有效):

uvx --from git+https://github.com/jiayunlimailutorontoca/mijia-home-mcp mijia-home-mcp login

2. 添加到 Claude Code(只读模式):

claude mcp add mijia-home -- uvx --from git+https://github.com/jiayunlimailutorontoca/mijia-home-mcp mijia-home-mcp serve

或者写入项目 .mcp.json / Claude Desktop 配置:

{
  "mcpServers": {
    "mijia-home": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/jiayunlimailutorontoca/mijia-home-mcp",
        "mijia-home-mcp",
        "serve"
      ]
    }
  }
}

3. 问一句"家里现在什么情况",模型会调用 get_home_snapshot。

下文示例统一用简写 mijia-home-mcp serve ...,实际命令替换为上面的 uvx --from git+... mijia-home-mcp serve ...;本地 clone 后 uv run mijia-home-mcp ... 也等价。

开启控制(可选)

# 允许控制普通设备(锁/摄像头/燃气与水阀/保险柜仍被拦截)
claude mcp add mijia-home -- uvx --from git+https://github.com/jiayunlimailutorontoca/mijia-home-mcp mijia-home-mcp serve --enable-control

# 只允许控制名单内设备(glob 匹配设备名/did/model,可多次传入)
mijia-home-mcp serve --enable-control --allow "客厅*" --allow "*台灯*"

# 黑名单优先于白名单
mijia-home-mcp serve --enable-control --deny "*camera*"

# 明确允许危险设备(不推荐)
mijia-home-mcp serve --enable-control --allow-dangerous

安全策略细则:

• 危险设备只接受精确放行:--allow "*" 这类通配白名单会放行普通设备,但锁/摄像头/燃气与水阀/保险柜必须把完整设备名或 did 精确写进 --allow(或使用 --allow-dangerous)才可控制。

• run_speaker_command 按危险通道对待:小爱语音指令可以触达全屋任意设备(包括门锁),会绕过设备白名单,因此默认拦截——需要把音箱名精确加入 --allow 或使用 --allow-dangerous。

• run_scene 不受设备白名单约束:场景内容是你在米家 App 预定义的动作组合,开启控制后即可执行;不想让 AI 碰的动作不要做成手动场景。

• 所有写操作(含被拒绝的尝试)都会追加到 ~/.config/mijia-home-mcp/audit.log。

局域网部署(可选)

mijia-home-mcp serve --transport http --host 0.0.0.0 --port 8423

claude mcp add --transport http mijia-home http://<host>:8423/mcp

⚠️ http 传输当前没有内置鉴权:监听 0.0.0.0 意味着同网段任何人都能读取(开启控制时还能操作)你的米家设备。只在可信局域网内使用并配合防火墙,切勿暴露公网。

工具一览

读(始终可用):

控制(需 --enable-control):

配置

CLI 参数优先,也支持环境变量(适合写进 .mcp.json 的 env):

已知边界

• 走小米云端接口(上游 mijia-api 逆向实现),状态读取有秒级延迟,无本地直连与事件推送;请控制轮询频率。

• 凭证约一个月需重新扫码一次(mijia-home-mcp login,或对话里直接调 login 工具)。

• 工具的 readOnlyHint 等注解只是提示;真正的安全边界在服务端(只读默认 + 白名单 + 危险设备拦截)。

• 个别设备的规格页缺少中文 i18n 数据(常见于红外遥控类设备,如空调伴侣里的"空调"),上游 spec 解析会失败;这类设备会出现在快照的 attention.spec_errors 里,状态为空但不影响其他设备。

• get_home_changes 的对比基线按 home 参数分开存储;跨口径调用(这次传 home、下次不传)各自维护基线。

开发

uv venv && uv pip install -e ".[dev]"
uv run pytest

测试完全离线(FakeAPI + 磁盘 spec 缓存),不需要米家账号。

许可证

GPL-3.0-or-later。依赖 mijia-api(GPL-3.0,其 README 声明仅供学习交流、禁止商用),本项目同样仅供学习交流使用。