米家 MCP Server

中文文档 | English

一个基于 mijiaAPI 3.x 的产品化米家 MCP 服务。它不再要求客户端先理解 did、siid/piid/aiid 这些协议细节，而是优先面向“家庭、房间、设备名、场景名”提供更自然的查询和控制能力。

这版解决什么问题

• 面向 AI 客户端：优先暴露稳定、清晰的产品级工具，而不是底层协议字段
• 面向真实家庭场景：先看家庭与房间，再定位设备，再执行控制
• 面向 MCP 标准：工具返回结构化结果，服务状态和登录状态可直接被客户端消费
• 面向扩展：标准能力 schema、profile 驱动控制、资源模型可以继续演进

当前能力

服务与登录

• get_service_status
• prepare_login
• reconnect_service
• clear_saved_login
• refresh_devices
• get_tool_catalog
• ping

家庭与设备

• get_home_overview
• list_homes
• list_devices
• get_device
• get_device_status
• get_device_capabilities

设备控制

• control_by_intent
• control_device
• turn_on_device
• turn_off_device
• set_brightness
• set_color_temperature
• set_target_temperature
• set_hvac_mode
• set_fan_speed
• set_cover_position

场景与耗材

• list_scenes
• execute_scene
• get_consumable_items

MCP 资源

• mijia://service
• mijia://homes
• mijia://devices
• mijia://scenes
• mijia://capabilities
• mijia://tooling

安装

建议使用 Python 3.10+。

poetry install

如果你不用 Poetry：

pip install -r requirements.txt

启动

poetry run python mcp_server/mcp_server.py

测试握手：

poetry run python mcp_server/mcp_test.py

登录方式

mijiaAPI 3.x 已移除账号密码登录，只支持二维码登录。

首次需要登录时，服务会：

• 生成浏览器页：~/.miot-mcp/qr.html
• 同时生成二维码图片：~/.miot-mcp/qr.png
• 默认优先用系统浏览器打开 qr.html
• 只有浏览器打不开时，才回退到图片查看器或终端二维码

认证信息会保存到：

~/.miot-mcp/auth_data.json

推荐登录主路径

1. 调用 prepare_login
2. 调用 get_service_status
3. 读取 service.qr.page_path 或 service.qr.image_path
4. 完成扫码后调用 reconnect_service 或直接 refresh_devices

登录相关状态

get_service_status 和 mijia://service 都会返回结构化登录状态，重点字段包括：

• service.connected
• service.has_saved_login
• service.qr.open_mode
• service.qr.page_path
• service.qr.image_path
• service.qr.login_url
• assistant_summary
• next_steps.should_scan_qr

环境变量

export MIJIA_ENABLE_QR="true"
export MIJIA_QR_OPEN_MODE="browser"
export MIJIA_LOG_LEVEL="INFO"

说明：

• MIJIA_ENABLE_QR：是否启用二维码登录，默认 true
• MIJIA_QR_OPEN_MODE：高级配置，支持 browser / viewer / none，默认 browser
• MIJIA_LOG_LEVEL：日志级别，支持 DEBUG / INFO / WARNING / ERROR

MCP 客户端配置示例

推荐直接使用虚拟环境里的 Python，而不是 poetry run。

{
  "mcpServers": {
    "mijia": {
      "command": "/path/to/venv/bin/python",
      "args": [
        "/path/to/miot-mcp/mcp_server/mcp_server.py"
      ],
      "env": {
        "MIJIA_ENABLE_QR": "true",
        "MIJIA_QR_OPEN_MODE": "browser",
        "MIJIA_LOG_LEVEL": "INFO"
      }
    }
  }
}

推荐调用路径

对于大多数 AI 客户端，建议优先这样使用：

1. prepare_login
2. get_service_status
3. refresh_devices
4. get_home_overview
5. get_device_status
6. control_by_intent
7. list_scenes
8. execute_scene

如果客户端需要更稳定、更显式的路由，再补充：

1. list_homes
2. list_devices
3. get_device
4. get_device_capabilities
5. control_device

常用工具说明

prepare_login

主动准备二维码登录。默认优先复用已有二维码页；如果需要重新走一轮扫码，可以传 force_reauth=true。

get_service_status

返回服务连接状态、认证文件路径、日志路径、二维码页路径、下一步建议。

get_home_overview

按家庭和房间输出设备总览，适合客户端先理解家庭结构。

get_device_status

查看单个设备当前状态、可用操作和推荐下一步。

get_device_capabilities

返回标准能力 schema 和 profile 驱动控制项，适合需要稳定路由的客户端。

control_by_intent

自然语言式控制入口。适合大多数日常使用场景，例如“把卧室台灯亮度调到 30%”。

control_device

统一结构化控制入口。适合客户端已经知道目标操作和参数时使用。

speaker_say

让小爱音箱语音播报任意文本（"喊话"）。适合长任务完成提醒、闹钟式播报、指定某台音箱念文字。

{
  "name": "speaker_say",
  "arguments": {
    "text": "任务完成啦，图片已生成",
    "speaker_name": "城市之光音响"
  }
}

为什么用 play-text 而不是 execute-text-directive：

小爱音箱有两个相关动作：

• execute-text-directive — 把文本当问题/指令发给小爱解析 → 会触发它的 AI 回答（如"被你问住了"），不是纯播报
• play-text — 纯播放文本，参数 _in=[text] 单参，不触发 AI 对话 ← speaker_say 用这个

坑：通用 run_action 路径把参数塞进 value 字段会导致云 API 报 -704220025 Action参数个数不匹配，必须用 _in kwargs 姿势（device.run_action('play-text', _in=[text]) → method['in']=[text]）。

命令行方式（无需 MCP 客户端，直接脚本调用）：

python speaker_say.py "任务完成啦" --speaker "城市之光音响"
python speaker_say.py "任务完成啦" --speaker "客厅音箱" --quiet   # 静默（只执行不播报）

参数：

• text：要念的文本（自然语言）
• --speaker：音箱名称（模糊匹配，不传选第一台在线音箱）
• --quiet：静默执行（不语音播报）

使用示例

查看服务状态

{
  "name": "get_service_status",
  "arguments": {}
}

主动准备登录

{
  "name": "prepare_login",
  "arguments": {
    "reopen_qr": true
  }
}

刷新设备与房间映射

{
  "name": "refresh_devices",
  "arguments": {}
}

查看家庭总览

{
  "name": "get_home_overview",
  "arguments": {}
}

查看单个设备状态

{
  "name": "get_device_status",
  "arguments": {
    "device_name": "吸顶灯",
    "room": "客厅"
  }
}

查看能力 schema

{
  "name": "get_device_capabilities",
  "arguments": {
    "device_name": "台灯",
    "room": "卧室"
  }
}

自然语言控制

{
  "name": "control_by_intent",
  "arguments": {
    "query": "把卧室台灯亮度调到30%"
  }
}

结构化控制

{
  "name": "control_device",
  "arguments": {
    "operation": "set_color_temperature",
    "device_name": "台灯",
    "room": "卧室",
    "value": 4000
  }
}

执行场景

{
  "name": "execute_scene",
  "arguments": {
    "scene_name": "回家模式"
  }
}

当前边界

这版 MCP 重点覆盖的是最常见的家庭控制路径：

• 家庭与房间浏览
• 设备定位
• 通用能力控制
• 标准化能力 schema 暴露
• 场景执行
• 耗材查询

已重点覆盖的典型能力包括：

• 开关
• 亮度
• 色温
• 目标温度
• 模式
• 风速
• 开合位置

更底层、更强定制的能力仍然可以继续往 control_device 扩展，但不再作为默认使用方式对外暴露。

代码结构

当前服务内部主要有三层：

• adapter/ 负责与 mijiaAPI 交互、登录、设备发现和二维码登录体验
• mcp_server/core/ 负责结果封装、能力计算、意图路由、标准化
• mcp_server/device_definitions/ 与 mcp_server/device_resources/ 负责标准能力定义、意图定义和产品化资源模型

当前能力和路由不依赖插件自动发现，而是显式导入定义表。这样更清晰，也更适合 AI 客户端稳定调用。

DSH（DeepSeek Harness）集成插件

本仓库除 MCP 服务外，还附带一个 DeepSeek Harness 的 Cordis 插件（dsh-plugin/dsh-task-notify），让 DSH agent 能主动用小爱音箱喊话 + 飞书通知（长任务完成提醒）：

工具	作用
notify_user(text, speaker?, force_speak?)	长任务完成通知：飞书私聊必发 + 按勿扰状态决定是否用小爱音箱喊话
speaker_say(text, speaker_name?)	让指定小爱音箱念任意文本（纯播放，不触发小爱 AI 对话）
set_notify_state(field, value)	切勿扰开关 / 切当前音箱 / 改飞书目标（跨会话持久化）
get_notify_state()	查当前状态

安装 DSH 插件

# 1. 复制到 DSH profiles 的 node_modules
cp -r dsh-plugin/dsh-task-notify C:\Users\<you>\.dsh\profiles\node_modules\@oadank\dsh-task-notify

# 2. 注册到 ~/.dsh/profiles/web/cordis.patch.yml 的 insert 列表
- id: dsh-task-notify
  name: '@oadank/dsh-task-notify'

# 3. 重启 dsh-web 生效

插件调用 speaker_say.py（本仓库）完成小爱播报，默认音箱可用 set_notify_state(currentSpeaker, "音箱名") 切换，状态存 ~/.dsh/profiles/notify-state.json 跨会话持久化。

详细说明见 dsh-plugin/README.md。