xiaomi-device-control

小米/米家智能家居 Claude Code Plugin，通过自然语言控制米家设备。

功能

• 列出所有米家设备
• 根据名称搜索设备
• 云端读取设备属性（开关状态、温度、PM2.5等）
• 云端设置设备属性（开关、亮度、模式等）
• 云端调用设备动作（开始清扫等）
• 自然语言场景联动（"我要睡觉了" -> 多设备操作）
• 摄像头截图与视觉感知（通过 RTSP 或 mock 图片）

架构

                Claude Code
                    |
    +---------------+---------------+
    |                               |
  Skill                        MCP Server
  (自然语言 -> 设备操作)        (5 个工具)
                                    |
                             小米云端 API
                            (MIoT 协议)
                                    |
                              米家设备

• MCP Server: 底层连接层，提供 5 个标准化工具，通过小米云端 API 控制设备
• Skill: 上层智能层，将自然语言指令映射为设备操作流程
• Plugin: 打包层，一键安装 MCP + Skill

安装

方式一：Claude Plugin（推荐）

在 Claude Code 交互界面中执行：

/plugin marketplace add alleneee/xiaomi-device-control
/plugin install xiaomi-home@alleneee-xiaomi-device-control

或在命令行中执行：

claude plugin marketplace add alleneee/xiaomi-device-control
claude plugin install xiaomi-home@alleneee-xiaomi-device-control

方式二：手动安装

git clone https://github.com/alleneee/xiaomi-device-control.git
cd xiaomi-device-control
uv sync

在 ~/.claude/settings.json 的 mcpServers 中添加：

{
  "xiaomi-home": {
    "command": "uv",
    "args": ["run", "--directory", "/path/to/xiaomi-device-control", "python", "-m", "src.server"]
  }
}

复制 skills/xiaomi-home/ 到 ~/.claude/skills/xiaomi-home/。

首次使用时在对话中告诉 Claude 配置小米账号即可，无需手动设置环境变量。

配置

方式一：对话中配置（推荐）

安装插件后，直接告诉 Claude：

用户: 帮我配置小米账号
Claude: 请提供你的小米账号和密码
用户: 账号 xxx 密码 xxx
Claude: (调用 xiaomi_setup) 验证码已发送到你的手机 138****1234
用户: 验证码是 123456
Claude: (调用 xiaomi_verify) 验证成功，找到 12 个设备

认证成功后 token 自动保存，后续无需重复配置。

方式二：环境变量配置

cp .env.example .env

编辑 .env：

MI_USERNAME=你的小米账号
MI_PASSWORD=你的密码
MI_CLOUD_COUNTRY=cn

首次登录需完成二次验证：

uv run python -m src.auth_helper
uv run python -m src.auth_helper verify <验证码>

认证成功后会保存 token 到 .mi_token，后续无需重复验证。

可用工具

工具	说明
xiaomi_auth_status	检查认证状态
xiaomi_setup	配置账号并发起登录
xiaomi_verify	提交二次验证码
xiaomi_list_devices	列出所有设备
xiaomi_find_device	根据名称搜索设备
xiaomi_get_properties	云端读取设备属性
xiaomi_set_property	云端设置设备属性
xiaomi_call_action	云端调用设备动作
xiaomi_camera_list	列出已配置的摄像头
xiaomi_camera_add	添加/更新摄像头配置
xiaomi_camera_remove	移除摄像头配置
xiaomi_camera_snapshot	从摄像头截取图片

MIoT 协议说明

设备属性通过 siid(服务ID) 和 piid(属性ID) 定位，查询设备规格：https://home.miot-spec.com

常见组合：

• 开关：siid=2, piid=1（true/false）
• 亮度：siid=2, piid=2（0-100）
• 色温：siid=2, piid=3
• 空气净化器模式：siid=2, piid=5
• PM2.5：siid=3, piid=6

项目结构

xiaomi-device-control/
├── .claude-plugin/
│   ├── plugin.json            # 插件元数据
│   └── marketplace.json       # 插件市场清单
├── .mcp.json                  # MCP Server 声明
├── skills/
│   └── xiaomi-home/
│       └── SKILL.md           # Skill 定义
├── src/                       # MCP Server 源码
│   ├── server.py              # FastMCP Server（5个工具）
│   ├── xiaomi_client.py       # 设备操作封装
│   ├── micloud.py             # 小米云端 API 客户端
│   ├── camera.py              # 摄像头截图（RTSP/Mock）
│   ├── auth_helper.py         # 认证辅助（二次验证）
│   └── config.py              # 配置管理
├── mock_images/               # 测试用 mock 图片
├── .env.example
├── pyproject.toml
└── README.md

使用示例

用户: 把电暖器打开
Claude: 搜索设备 -> 找到电暖器 did -> 设置 siid=2, piid=1, value=true -> "已开启米家石墨烯智能电暖器"

用户: 空气质量怎么样
Claude: 搜索净化器 -> 读取 PM2.5 -> "当前 PM2.5: 46，空气质量良好"

用户: 我要睡觉了
Claude: 关灯 + 净化器切睡眠模式 + 电暖器调低温度 -> 逐一汇报结果

用户: 看看门口有没有人
Claude: 截图 -> 分析图片 -> "门口有一个快递员，要开门灯吗？"

摄像头功能

通过 Micam 或其他 RTSP 桥接服务，可将小米摄像头视频流接入本项目。

前置条件

• 部署 Micam（Docker）获取 RTSP 流地址
• 本机安装 ffmpeg（brew install ffmpeg）

配置摄像头

用户: 添加门口摄像头，地址是 rtsp://192.168.1.100:8554/door
Claude: (调用 xiaomi_camera_add) 已添加摄像头"门口"

测试模式（无需真实摄像头）

将测试图片放入 mock_images/ 目录，使用 mock:// 协议：

用户: 添加测试摄像头，地址是 mock://test.jpg
Claude: (调用 xiaomi_camera_add) 已添加摄像头

用户: 看看测试摄像头
Claude: (调用 xiaomi_camera_snapshot -> 读取图片) 图中是一张测试图片...

mock:// 支持单个文件或目录（轮询目录内图片）。

许可证

MIT