米家 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

登录相关状态

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"
      }
    }
  }
}

常用工具说明

`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`

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

使用示例

查看服务状态

{
  "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 客户端稳定调用。