MCP Server

mijiaAPI 提供了 MCP (Model Context Protocol) server，可以让 LLM（如 Claude）直接控制米家设备，无需编写代码。

启动 MCP server

# 直接在命令中指定带 mcp extra 的包（注意引号，否则 shell 会把 [] 当作通配符）
uvx "mijiaAPI[mcp]" mcp

# 或指定认证文件路径
uvx "mijiaAPI[mcp]" mcp -p /path/to/auth.json

若 uv 版本较旧不支持上述写法，可使用 --from 形式：uvx --from "mijiaAPI[mcp]" mijiaAPI mcp。

安装时若已经指定 mijiaAPI[mcp]，也可直接运行 mijiaAPI mcp。

客户端配置

在 MCP 客户端（如 Claude Desktop、Cursor）的配置文件中添加：

{
  "mcpServers": {
    "mijia-api": {
      "command": "uvx",
      "args": ["mijiaAPI[mcp]", "mcp"]
    }
  }
}

指定认证文件路径时：

{
  "mcpServers": {
    "mijia-api": {
      "command": "uvx",
      "args": ["mijiaAPI[mcp]", "mcp", "-p", "/path/to/auth.json"]
    }
  }
}

可用工具

MCP server 暴露以下工具供 LLM 调用：

工具	说明
login	发起米家二维码登录：先尝试刷新 token，失败则生成二维码并在后台长轮询等待扫码，返回二维码图片链接
login_status	查询 login 发起的登录结果（pending/success/error），成功后自动切换为新凭证
list_homes	列出所有家庭及房间信息
list_devices	列出设备列表（含共享设备），可按家庭过滤
list_scenes	列出手动场景，可按家庭过滤
list_consumables	列出耗材信息，可按家庭过滤
get_device_spec	获取设备规格（属性和动作列表），用于确定可用参数名
get_device_properties	获取设备属性值（高层封装，按属性名读取，无需 siid/piid）
set_device_property	设置设备属性值（高层封装，按属性名写入）
run_device_action	执行设备动作（高层封装，按动作名执行）
run_scene	运行手动场景（按 ID 或名称）
get_statistics	获取设备统计数据（如耗电量、使用时长）
run_speaker_command	通过小爱音箱执行自然语言指令（默认静默）
speaker_play	通过小爱音箱朗读指定文本

小爱音箱：执行命令与播放文本

• run_speaker_command(prompt="打开卧室台灯", speaker_name="卧室小爱")：通过 execute-text-directive 执行自然语言控制指令；quiet 默认为 true（不播报回复）， 传入 quiet=false 可播报回复。
• speaker_play(text="你好，我是小爱同学", speaker_name="卧室小爱")：通过 play-text 朗读指定文本，不将其当成控制指令执行；没有 quiet 参数。

两种操作在未指定 speaker_name 时都默认选择设备列表中的第一台小爱音箱。 这些工具是向音箱发送文字，不是接收音箱语音输入。

统计数据

get_statistics 接收设备 did、统计键 key、统计类型 data_type，以及可选的 limit、 time_start、time_end。未指定时间时默认查询最近 30 天，最多返回 6 条。

常用统计类型为 stat_hour_v3、stat_day_v3、stat_week_v3、stat_month_v3；较旧设备 可能使用不带 _v3 的对应类型。key 同样依赖设备型号，例如 lumi.acpartner.mcn04 的耗电量使用 "7.1"，lumi.acpartner.mcn02 使用 "powerCost"。

工具返回 JSON 编码的统计条目列表，每项通常包含 Unix 秒级时间戳 time 和字符串 value。value 可能仍是 JSON 数组字符串，例如 "[48.476]"。统计接口仅支持部分设备， 不同型号可能使用不同 API，详见 issue #46 和 米家统计接口文档。

会话内登录流程

当凭证过期且自动刷新失败时，LLM 可按以下步骤在会话内完成登录，无需重启 server：

1. 调用 login：server 先尝试刷新 token；若仍不可用，则生成二维码，在后台线程长轮询等待扫码，并返回二维码图片链接。
2. 用户用米家APP在 2 分钟内扫描 login 返回的二维码图片。
3. 调用 login_status 查询结果：
   • pending：仍在等待扫码，稍后再次查询。
   • success：登录成功，已切换为新凭证，后续工具调用将使用新凭证。
   • error：登录失败，返回错误信息，可重新调用 login。

WARNING

login 不会阻塞 server——它在后台线程等待扫码，因此 LLM 在等待期间可以继续响应，但设备控制工具在登录完成前仍会失败。

典型用法

先用 list_devices 获取设备，用 get_device_spec 查询设备支持的属性/动作名，再用 get_device_properties / set_device_property / run_device_action 控制设备。遇到认证失效时，按上文“会话内登录流程”调用 login + login_status。