melcloud-ac

MELCloud AC Control (Python CLI + MCP)

Simple project to control Mitsubishi Electric AC units through MELCloud.

Goal

This repository is designed as an LLM-ready execution backend. An LLM/agent can interpret natural language and call this project (CLI or MCP) to perform real AC actions.

It supports:

• MELCloud authentication
• device listing
• power on/off per room
• target temperature changes

---

1) Requirements

• Python 3.10+
• A MELCloud account with configured devices

Install dependencies:

cd integrations/melcloud-ac
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

---

2) Configuration

Create your local environment file:

cp .env.example .env

Fill in your credentials:

MELCLOUD_EMAIL=your_email
MELCLOUD_PASSWORD=your_password
MELCLOUD_LANGUAGE=0
# Optional: lock to a specific building/home name
# MELCLOUD_BUILDING=Home

⚠️ Never commit .env.

---

3) Usage

Option A: CLI (simple)

List devices:

python control_ac.py list

Power control:

python control_ac.py power office on
python control_ac.py power office off

Set temperature:

python control_ac.py temp office 22

Smart automatic control (decides mode + target temperature from room temp):

python control_ac.py auto office

Custom thresholds/targets:

python control_ac.py auto office --cool-above 26 --heat-below 19 --cool-target 23 --heat-target 22 --neutral-target 23 --neutral-mode auto

Notes:

• Device resolution is alias-free and generic: the client fetches your MELCloud devices and picks the best match (with ambiguity safeguards).
• Temperature guardrail in client: 16°C to 31°C.

Option B: MCP server (for LLM clients)

An MCP wrapper is included in mcp_server.py with 4 tools:

• list_devices()
• set_power(room, state)
• set_temperature(room, value)
• auto_comfort(room, ...) (smart mode + target temperature selection)

Run MCP server:

python mcp_server.py

Example MCP client configuration (generic):

{
  "mcpServers": {
    "melcloud-ac": {
      "command": "python",
      "args": ["/path/to/integrations/melcloud-ac/mcp_server.py"],
      "env": {
        "MELCLOUD_EMAIL": "...",
        "MELCLOUD_PASSWORD": "...",
        "MELCLOUD_LANGUAGE": "0"
      }
    }
  }
}

Tip: you can either pass env in your MCP client config or rely on local .env.

---

4) Project structure

melcloud-ac/
├── control_ac.py        # Main CLI
├── mcp_server.py        # MCP wrapper for LLM tools
├── melcloud_client.py   # MELCloud API client (auth + actions)
├── requirements.txt
├── .env.example
└── README.md

---

5) LLM integration examples

Typical flow:

1. User says: “Turn on office AC”
2. LLM maps intent to action (power on, room=office)
3. LLM executes CLI or MCP tool
4. LLM returns a friendly response

Natural language → CLI mapping examples:

• “Turn on office AC”
• python control_ac.py power office on

• “Turn off living room AC”
• python control_ac.py power sala off

• “Set office AC to 22 degrees”
• python control_ac.py temp office 22

• “What devices are available?”
• python control_ac.py list

Quick Python wrapper example:

import json
import subprocess


def ac_command(*args: str) -> dict:
    proc = subprocess.run(
        ["python", "control_ac.py", *args],
        capture_output=True,
        text=True,
        check=False,
    )
    try:
        return json.loads(proc.stdout)
    except json.JSONDecodeError:
        return {"ok": False, "error": proc.stdout or proc.stderr}

print(ac_command("list"))
print(ac_command("power", "office", "on"))
print(ac_command("temp", "office", "22"))

Function-calling schema example:

{
  "name": "ac_control",
  "description": "Control MELCloud AC by room",
  "parameters": {
    "type": "object",
    "properties": {
      "action": { "type": "string", "enum": ["list", "power", "temp"] },
      "room": { "type": "string" },
      "state": { "type": "string", "enum": ["on", "off"] },
      "value": { "type": "number" }
    },
    "required": ["action"]
  }
}

---

6) Quick troubleshooting

• Login error: verify email/password and MELCloud account.
• Room not found: run python control_ac.py list and use the exact device name.
• Network timeout: check connectivity and MELCloud availability.

---

7) Next improvements (optional)

• consolidated status command
• mode support (heat/cool/auto) and fan speed
• automated tests (requests mocking)