内容
# midea-mcp
面向美的空调的本地单用户 MCP Server。MVP 使用 Python 3.12、MCP Python
SDK `>=1.27,<2` 和 stdio，公开六个工具：
- `list_devices`
- `get_device`
- `refresh_device`
- `set_device_state`
- `discover_lan_devices`
- `diagnose_device`
## 安全与一致性保证
- 每台逻辑设备使用 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 支持空调状态读取及开关、模式、目标温度写入，并使用云端状态读回核验。
## 安装
```powershell
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. 局域网扫描
```powershell
.\.venv\Scripts\midea-mcp.exe phase0
```
跨子网或广播受限时可指定设备 IP 或广播地址：
```powershell
.\.venv\Scripts\midea-mcp.exe phase0 --target 192.168.1.255
```
### 2. 导入旧 HA V3 凭证
`midea_ac_lan` 的单设备文件通常位于：
```text
<HA config>/.storage/midea_ac_lan/<device_id>.json
```
可导入单个文件、整个 `midea_ac_lan` 目录，也可导入 HA
`.storage/core.config_entries`：
```powershell
.\.venv\Scripts\midea-mcp.exe import-ha C:\path\to\123456789.json
```
导入器仅接受设备类型 `0xAC`、协议版本 V3，并将 Token/Key 立即加密后保存。
### 3. 可选的 Cloud 库存及 Token/Key 补取
不要把账号密码写入命令行历史：
```powershell
$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. 加密备份
```powershell
.\.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
```powershell
.\.venv\Scripts\midea-mcp-server.exe
```
客户端配置示例：
```json
{
"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` 只接受：
```json
{
"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
- 多用户或公网认证
## 测试
```powershell
.\.venv\Scripts\python.exe -m pytest
.\.venv\Scripts\python.exe -m ruff check .
```
测试使用模拟 Provider，不会控制真实设备。实机写入只通过显式调用
`set_device_state` 发生。
本次 Phase 0 与实机验收结果见 [PHASE0.md](PHASE0.md)。项目已发现并登记
一台 V3 空调，通过云端 Token API 候选完成 LAN 认证，并实际验证开关、模式
和温度控制。验收结束后设备已恢复为关机、25°C。
## Acknowledgments
- [wuwentao/midea_ac_lan](https://github.com/wuwentao/midea_ac_lan) — LAN 协议参考，MIT
- [sususweet/midea_auto_cloud](https://github.com/sususweet/midea_auto_cloud) — 云端 API 和设备映射，Apache-2.0
- [hasscc/meiju](https://github.com/hasscc/meiju) — 协议研究，Apache-2.0
- [Do1e/mijia-mcp](https://github.com/Do1e/mijia-mcp) — MCP 架构参考
Unofficial community project, not affiliated with Midea Group.
