Content
# midea-mcp
Local single-user MCP Server for Midea air conditioners. MVP uses Python 3.12, MCP Python SDK `>=1.27,<2` and stdio, exposing six tools:
- `list_devices`
- `get_device`
- `refresh_device`
- `set_device_state`
- `discover_lan_devices`
- `diagnose_device`
## Security and Consistency Guarantees
- Each logical device uses an internal UUID within midea-mcp.
- Cloud ID, LAN ID, and keyed SN fingerprint are saved as bindings, never assuming Cloud ID equals LAN ID.
- Writes return only `rejected`, `not_delivered`, `delivery_unknown`, `accepted`, or `verified`.
- When LAN or Cloud write delivery results are unknown, verification is done by reading the actual state through the original Provider, never switching Providers or resending.
- Tokens/Keys are encrypted with AES-256-GCM; logs and tool responses do not return plaintext credentials or raw SNs.
- Routing prioritizes available LAN; if no LAN binding is available, Cloud is used. Once a write starts, the request locks onto the Provider.
- Cloud supports reading AC states and writing power, mode, and target temperature, with state reads verifying changes.
## Installation
```powershell
py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
```
If the system lacks the `py` command, use the Python 3.12 executable directly to create a virtual environment.
The default data directory is `data/` in the current directory, modifiable via `MIDEA_MCP_DATA_DIR`.
The `data/master.key` is generated on the first run. For production use, back up the key and restrict file access;
alternatively, inject a URL-safe base64-encoded 32-byte key using `MIDEA_MCP_MASTER_KEY`.
## Phase 0
### 1. LAN Scanning
```powershell
.\.venv\Scripts\midea-mcp.exe phase0
```
For cross-subnet or restricted broadcasts, specify the device IP or broadcast address:
```powershell
.\.venv\Scripts\midea-mcp.exe phase0 --target 192.168.1.255
```
### 2. Importing Old HA V3 Credentials
`midea_ac_lan` single-device files are typically located at:
```text
<HA config>/.storage/midea_ac_lan/<device_id>.json
```
Import a single file, the entire `midea_ac_lan` directory, or HA `.storage/core.config_entries`:
```powershell
.\.venv\Scripts\midea-mcp.exe import-ha C:\path\to\123456789.json
```
The importer only accepts device type `0xAC`, protocol version V3, and encrypts Tokens/Keys immediately.
### 3. Optional Cloud Inventory and Token/Key Retrieval
Do not write account passwords into command-line history:
```powershell
$env:MIDEA_ACCOUNT = "your-account"
$env:MIDEA_PASSWORD = "your-password"
$env:MIDEA_CLOUD_NAME = "Midea Meiju"
.\.venv\Scripts\midea-mcp.exe sync-cloud
```
The old Token API is being phased out by Midea, so this step may not yield new credentials. Existing HA credentials take priority and are not overwritten by cloud candidates. Cloud/LAN merge into a single device only when SN fingerprints uniquely match.
`sync-cloud` also registers Cloud bindings. When deploying on servers inaccessible to the home LAN, run this command at least once before starting the MCP Server; subsequently, `refresh_device` and `set_device_state` will work through Cloud routing.
### 4. Encrypted Backup
```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
```
Backups use a separate password derived through scrypt, then encrypted with AES-256-GCM.
## Starting MCP Server
```powershell
.\.venv\Scripts\midea-mcp-server.exe
```
Client configuration example:
```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"
}
}
}
}
```
## Control Parameters
`set_device_state` only accepts:
```json
{
"device_id": "midea-mcp-internal-uuid",
"changes": {
"power": true,
"mode": "cool",
"target_temperature": 26
}
}
```
Modes are `off / auto / cool / dry / heat / fan_only`; target temperature is limited to 17–30°C by default, with a 0.5°C step. `power=false` cannot be submitted with mode or temperature.
## Current Limitations
- Water heaters, ovens, and other device categories
- Scenes and `execute_scene`
- Home Assistant Provider
- Multi-user or public network authentication
## Testing
```powershell
.\.venv\Scripts\python.exe -m pytest
.\.venv\Scripts\python.exe -m ruff check .
```
Testing uses simulated Providers and does not control real devices. Actual writes occur only through explicit `set_device_state` calls.
This Phase 0 and real-device acceptance results are in [PHASE0.md](PHASE0.md). One V3 AC was found, registered through the cloud Token API candidate, and verified for power, mode, and temperature control. The device was returned to an off state at 25°C after verification.
## Acknowledgments
- [wuwentao/midea_ac_lan](https://github.com/wuwentao/midea_ac_lan) — LAN protocol reference, MIT
- [sususweet/midea_auto_cloud](https://github.com/sususweet/midea_auto_cloud) — Cloud API and device mapping, Apache-2.0
- [hasscc/meiju](https://github.com/hasscc/meiju) — Protocol research, Apache-2.0
- [Do1e/mijia-mcp](https://github.com/Do1e/mijia-mcp) — MCP architecture reference
Unofficial community project, not affiliated with Midea Group.
