midea-mcp

midea-mcp

面向美的空调的本地单用户 MCP Server。MVP 使用 Python 3.12、MCP Python SDK >=1.27,<2 和 stdio，公开七个工具：

• list_devices
• get_device
• get_device_log
• refresh_device
• set_device_state
• discover_lan_devices
• diagnose_device

设备状态日志

所有 set_device_state 调用都会写入 data/device-log.jsonl，包括请求字段、 Provider、五种写入状态、核验结果和失败原因。每次真实设备状态读取都会与上一份 持久化快照比较，并分别记录：

• state_change：开关、模式、设定温度；
• sensor_change：室内温度；
• availability_change：在线状态；
• state_snapshot：首次读取时建立的基线。

每条记录同时包含 UTC 和北京时间。通过 midea-mcp 写入后的读回带有同一个 request_id；其他入口造成的变化标记为 external_unknown。observed_via=cloud 只表示变化是通过云端读取发现的，不能证明操作来自美居 App。

读取最近日志：

get_device_log(limit=50)
get_device_log(limit=50, field="mode")
get_device_log(limit=50, event_type="state_change")

可过滤字段为 power、mode、target_temperature、current_temperature 和 online，limit 范围为 1–500。日志只在真实状态读取发生时发现外部变化； midea-mcp 本身不会后台轮询设备。

安全与一致性保证

• 每台逻辑设备使用 midea-mcp 内部 UUID。
• Cloud ID、LAN ID 和 keyed SN fingerprint 分别保存为 bindings，绝不假设 Cloud ID 与 LAN ID 相同。
• 写入只返回 rejected、not_delivered、delivery_unknown、accepted 或 verified。
• LAN 或 Cloud 写入投递结果不明时，只通过原 Provider 读取实际状态进行核验， 绝不切换 Provider 或重发。
• Token/Key 使用 AES-256-GCM 加密落盘；日志和工具响应不返回明文凭证或原始 SN。
• 路由选择为“可用 LAN 优先；没有可用 LAN binding 时使用 Cloud”。一旦开始写入， 本次请求就锁定 Provider。
• Cloud 支持空调状态读取及开关、模式、目标温度写入，并使用云端状态读回核验。

安装

py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"

如果系统没有 py 命令，直接使用 Python 3.12 可执行文件创建虚拟环境。

默认数据目录是当前目录下的 data/，可通过 MIDEA_MCP_DATA_DIR 修改。 首次启动会生成 data/master.key。生产使用时应备份密钥并限制文件访问权限；也可以 使用 MIDEA_MCP_MASTER_KEY 注入一个 URL-safe base64 编码的 32 字节密钥。

Phase 0

1. 局域网扫描

.\.venv\Scripts\midea-mcp.exe phase0

跨子网或广播受限时可指定设备 IP 或广播地址：

.\.venv\Scripts\midea-mcp.exe phase0 --target 192.168.1.255

2. 导入旧 HA V3 凭证

midea_ac_lan 的单设备文件通常位于：

<HA config>/.storage/midea_ac_lan/<device_id>.json

可导入单个文件、整个 midea_ac_lan 目录，也可导入 HA .storage/core.config_entries：

.\.venv\Scripts\midea-mcp.exe import-ha C:\path\to\123456789.json

导入器仅接受设备类型 0xAC、协议版本 V3，并将 Token/Key 立即加密后保存。

3. 可选的 Cloud 库存及 Token/Key 补取

不要把账号密码写入命令行历史：

$env:MIDEA_ACCOUNT = "your-account"
$env:MIDEA_PASSWORD = "your-password"
$env:MIDEA_CLOUD_NAME = "美的美居"
.\.venv\Scripts\midea-mcp.exe sync-cloud

旧 Token API 正在被美的关闭，因此该步骤可能无法取得新凭证。已有 HA 凭证优先且 不会被云端候选覆盖。Cloud/LAN 只有在 SN fingerprint 唯一匹配时才合并为同一设备。

sync-cloud 同时会登记 Cloud binding。部署在无法访问家庭局域网的服务器时，应在 启动 MCP Server 前至少执行一次该命令；之后 refresh_device 和 set_device_state 会通过 Cloud 路由工作。

4. 加密备份

.\.venv\Scripts\midea-mcp.exe backup-credentials C:\safe\midea.backup.json
.\.venv\Scripts\midea-mcp.exe restore-credentials C:\safe\midea.backup.json

备份使用独立口令通过 scrypt 派生密钥，再使用 AES-256-GCM 加密。

启动 MCP Server

.\.venv\Scripts\midea-mcp-server.exe

客户端配置示例：

{
  "mcpServers": {
    "midea": {
      "command": "C:\\path\\to\\midea-mcp\\.venv\\Scripts\\midea-mcp-server.exe",
      "env": {
        "MIDEA_MCP_DATA_DIR": "C:\\path\\to\\midea-mcp\\data"
      }
    }
  }
}

控制参数

set_device_state 只接受：

{
  "device_id": "midea-mcp-internal-uuid",
  "changes": {
    "power": true,
    "mode": "cool",
    "target_temperature": 26
  }
}

模式为 off / auto / cool / dry / heat / fan_only，目标温度默认限制 为 17–30°C，步长 0.5°C。power=false 不能与模式或温度同时提交。

当前不做

• 热水器、烤箱及其他设备品类
• 场景和 execute_scene
• Home Assistant Provider
• 多用户或公网认证

测试

.\.venv\Scripts\python.exe -m pytest
.\.venv\Scripts\python.exe -m ruff check .

测试使用模拟 Provider，不会控制真实设备。实机写入只通过显式调用 set_device_state 发生。

本次 Phase 0 与实机验收结果见 PHASE0.md。项目已发现并登记 一台 V3 空调，通过云端 Token API 候选完成 LAN 认证，并实际验证开关、模式 和温度控制。验收结束后设备已恢复为关机、25°C。

Acknowledgments

• wuwentao/midea_ac_lan — LAN 协议参考，MIT
• sususweet/midea_auto_cloud — 云端 API 和设备映射，Apache-2.0
• hasscc/meiju — 协议研究，Apache-2.0
• Do1e/mijia-mcp — MCP 架构参考

Unofficial community project, not affiliated with Midea Group.