caroliny1031/midea-mcp

A safety-first MCP server for Midea air conditioners. LAN-preferred, cloud fallback.

About midea-mcp

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

- listdevices - getdevice - refreshdevice - setdevicestate - discoverlandevices - diagnosedevice

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

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

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

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

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

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

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

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

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

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

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

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

From the project README.

Maintaining this server?

Add the radar badge to your README — it shows your project was picked up by MCP Radar and links to this page:

[![On MCP Radar](https://mcp.liqiwa.com/badge.svg)](https://mcp.liqiwa.com/s/caroliny1031--midea-mcp.html)

Related MCP servers