小米家庭MCP服务器
通过AI助手控制您的小米智能家居设备 模型上下文协议（MCP）.
特性
- 设备发现 --自动查找小米帐户中的所有设备
- 状态监测 --读取电源状态、亮度、温度、湿度、电池、锁定状态
- 设备控制 --打开/关闭，调整亮度、色温、目标温度
- 小艾扬声器 --播放/暂停音乐、TTS、音量控制、语音命令
- 二维码登录 --使用Mi Home应用程序扫描，无需密码
- 零依赖设置 --只需两个Python文件，无需安装pip
快速开始
先决条件
- Python 3.10+
- 紫外线 （推荐）或pip
- 手机上的Mi Home应用程序（用于二维码登录）
1.登录
uv run --script login.py一个二维码将在您的浏览器中打开。使用Mi Home应用程序扫描（个人资料→ 右上角的扫描图标）。
令牌保存到 ~/.xiaomi-mcp/tokens.json 和 600 权限。
2.连接到克劳德代码
claude mcp add xiaomi-home -- uv run --script /path/to/mcp_server.py就是这样！现在，您可以与您的设备进行对话：
“打开灯” “室温是多少？” “门锁上了吗？” “将亮度设置为50%” “播放一些音乐”
2a。连接到克劳德桌面
添加到您的Claude桌面配置(~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"xiaomi-home": {
"command": "uv",
"args": ["run", "--script", "/path/to/mcp_server.py"]
}
}
}可用工具
| 工具 | 说明 |
|---|---|
get_devices() | 列出所有设备和在线状态 |
get_device_status(name?) | 查询详细状态（电源、亮度、温度、电池等） |
control_device(name, action) | 控制装置： on/off, brightness, color_temp, target_temp |
play_music(keyword?) | 在小艾扬声器上播放音乐 |
pause_music() | 暂停播放 |
resume_music() | 恢复播放 |
set_volume(volume) | 设置扬声器音量（0-100） |
tts(text) | 扬声器上的文本转语音 |
xiaoai_command(command) | 向小艾发送语音命令 |
get_speaker_status() | 获取播放状态 |
支持设备
服务器通过型号前缀自动检测设备类型：
| 类型 | 型号 | 状态查询 | 控件 |
|---|---|---|---|
| 灯光 | philips.light.*, yeelink.light.* | 电源、亮度 | 开/关、亮度、色温 |
| AC合作伙伴 | lumi.acpartner.* | 电源 | 开/关 |
| 加热器 | xiaomi.heater.* | 电源、目标温度 | 开/关、目标温度 |
| 风扇 | xiaomi.fan.* | 功率、速度、振荡 | 开/关 |
| 锁 | loock.lock.* | 锁定状态，电池 | -- |
| 传感器 | miaomiaoce.sensor_ht.* | 温度、湿度、电池 | -- |
| 演讲者 | xiaomi.wifispeaker.* | 播放状态 | 播放、暂停、音量、TTS |
| 水壶 | yunmi.kettle.* | 仅支持BLE（不支持） | -- |
注： MIoT规格属性（siid/piid）因型号而异。内置映射涵盖了常见模型。如果您的设备返回不正确的值，您可能需要在以下网址查找正确的规格 miot-spec.com 并调整MIOT_PROPSdict inmcp_server.py.
许可证管理
# Check if token is still valid
uv run --script login.py --check
# Clear cached token
uv run --script login.py --logout
# Re-login
uv run --script login.py代币的寿命很长，但可能会在几周/几个月后到期。如果MCP服务器开始出现故障，请重新运行 login.py.
备选方案：环境变量
如果您不想使用登录工具，可以直接传递凭据：
claude mcp add xiaomi-home \
-e XIAOMI_PASS_TOKEN="your_pass_token" \
-e XIAOMI_USER_ID="your_user_id" \
-e XIAOMI_DEVICE_ID="your_device_id" \
-- uv run --script /path/to/mcp_server.py要获取这些值，请登录 account.xiaomi.com 在浏览器中提取 passToken, userId，以及 deviceId 从饼干。
运作原理
Mi Home App (scan QR) → login.py → ~/.xiaomi-mcp/tokens.json
↓
Claude / Cursor ←→ MCP Protocol ←→ mcp_server.py ←→ Xiaomi Cloud API
(api.io.mi.com)- 认证：passToken→ serviceToken交换（自动刷新）
- 设备控制：MIoT规范协议（siid/piid）+传统miio RPC
- 演讲者：双通道--IoT（控制/TTS）+MiNA（音量/状态）
许可证
麻省理工学院