gree-ac-mcp-server

A Model Context Protocol (MCP) server that controls GREE / EWPE-compatible WiFi air conditioners directly over their native UDP protocol. No Homebridge, no cloud — it talks straight to the units on your LAN.

The GREE wire protocol (AES encryption, scan/bind/status/command flow) is implemented from scratch based on eibenp/homebridge-gree-airconditioner and tomikaa87/gree-remote.

• Two transports: MCP stdio (for Claude Desktop and other local clients) and http (modern Streamable HTTP and legacy HTTP+SSE), with mandatory bearer auth on HTTP.

• Both encryption schemes: v1 (AES-128-ECB) and v2 (AES-128-GCM), auto-detected per device.

• Background polling: each device is bound and polled continuously; tool calls fire immediately and the next poll confirms the new state.

Requirements

• Node.js >= 20

• The AC units must be on the same LAN/subnet as the server (UDP broadcast/unicast to port 7000).

Related MCP server: HomeAssistant MCP

Install & build

npm install
npm run build

Quick start

cp config.example.json config.json
# edit config.json: set bearerToken and your devices' mac/address

# stdio (local MCP clients)
npm run start:stdio -- --config ./config.json

# HTTP (network clients)
npm run start:http -- --config ./config.json --host 0.0.0.0 --port 8080

During development you can run the TypeScript directly with npm run dev:stdio / npm run dev:http.

CLI flags

The config file path may also be supplied via the GREE_MCP_CONFIG environment variable.

Configuration

JSON file validated with zod. On a validation error the server prints the offending field/device and exits non-zero. The server must be restarted to pick up config changes (hot-reload is not implemented).

Top-level fields

Per-device fields

Note on sensorOffset and temperature decoding. Most GREE units report the internal sensor (TemSen) as actual°C + 40. The server subtracts that fixed base offset to decode, then adds your sensorOffset as a calibration on top. So currentTemperature = TemSen − 40 + sensorOffset.

Swing position enums

• Vertical (SwUpDn): default, full, fixed-top, fixed-upper-middle, fixed-middle, fixed-lower-middle, fixed-bottom (plus swing-top/swing-upper-middle/swing-middle/swing-lower-middle/swing-bottom).

• Horizontal (SwingLfRig, only on units with horizontal louvers): default, full, fixed-left, fixed-center-left, fixed-center, fixed-center-right, fixed-right.

How to obtain a device's MAC

The MAC is the GREE device id (a 12-hex string, e.g. 502cc6aabbcc). Following the homebridge plugin's documented method, the easiest way is to run this server (or the homebridge plugin) with debug logging on the same LAN and watch the scan responses:

node dist/index.js --transport http --config ./config.json --log-level debug

Every discovered unit logs a device discovered line containing its mac, address, model and firmware version. Other options:

• Check your router's DHCP client list for the AC's WiFi adapter MAC (drop the colons, lowercase it).

• Use the official GREE+ / EWPE Smart app, or any GREE scan utility, which reports the device id.

MCP tools

Every tool accepts a device selector: mac (canonical) or name (alias, matched against config). Provide one of them. set_* tools fire the UDP command immediately and report "command sent"; the background poll loop confirms the new state shortly after. If a device is offline/unbound, write tools return an error instead of silently succeeding.

Each device is also exposed as a resource at gree://device/<mac> returning its decoded status as JSON.

Using with Claude Desktop (stdio)

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "gree-ac": {
      "command": "node",
      "args": [
        "/absolute/path/to/gree-ac-mcp-server/dist/index.js",
        "--transport", "stdio",
        "--config", "/absolute/path/to/config.json"
      ]
    }
  }
}

No bearer token is needed in stdio mode (the process pipe is the trust boundary).

HTTP usage

Bearer auth is mandatory on /mcp, /sse and /messages. Missing/invalid tokens get 401 with a WWW-Authenticate: Bearer header. /healthz is unauthenticated.

CORS (browser clients)

For browser-based MCP clients (e.g. the MCP Inspector) set corsOrigins in the config. CORS is disabled by default (no headers added), so non-browser clients like Claude Desktop are unaffected. When enabled:

• OPTIONS preflight is answered before auth (preflight carries no Authorization header).

• The Mcp-Session-Id response header is exposed so client JS can read the session id.

• Auth is still enforced on the actual request; only listed origins get an Access-Control-Allow-Origin.

// config.json
"corsOrigins": ["https://inspector.example.com"]   // or ["*"] to allow any origin

Health check

curl http://localhost:8080/healthz
# {"status":"ok","total":2,"bound":1,"unbound":1,"devices":[...]}

Modern Streamable HTTP

Initialize (note the required Accept header and that the session id comes back in a response header):

curl -i -X POST http://localhost:8080/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'
# -> response header:  Mcp-Session-Id: <uuid>

Then reuse that session id:

SID=<uuid-from-above>

# complete the handshake
curl -s -X POST http://localhost:8080/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" -H "Mcp-Session-Id: $SID" \
  -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'

# list devices
curl -s -X POST http://localhost:8080/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" -H "Mcp-Session-Id: $SID" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_devices","arguments":{}}}'

# turn a unit on
curl -s -X POST http://localhost:8080/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" -H "Mcp-Session-Id: $SID" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"set_power","arguments":{"mac":"502cc6aabbcc","on":true}}}'

Legacy HTTP+SSE

# 1) open the event stream (keeps running; prints the "endpoint" event with your sessionId)
curl -N http://localhost:8080/sse -H "Authorization: Bearer YOUR_TOKEN"

# 2) post messages to the endpoint reported by the stream (sessionId from the endpoint event)
curl -X POST "http://localhost:8080/messages?sessionId=YOUR_SESSION_ID" \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Docker

The image is multi-stage and runs as the non-root node user, defaulting to HTTP mode reading /config/config.json.

docker build -t gree-ac-mcp-server .
docker run --rm \
  --network host \
  -v "$(pwd)/config.json:/config/config.json:ro" \
  gree-ac-mcp-server

UDP discovery/broadcast needs L2 access to the AC's subnet. --network host is the simplest way to give the container that on Linux; otherwise set each device's address explicitly and ensure UDP/7000 routing to the units works from the container network.

The container EXPOSEs 8080. Override the entrypoint args to change transport/port, e.g. docker run ... gree-ac-mcp-server --transport http --config /config/config.json --port 9000.

Logging & security

• Logs are JSON lines on stderr (stdout is reserved for the MCP channel in stdio mode), including device mac, action, and outcome.

• The bearer token and all AES/device keys are never logged.

• Logs contain device identifiers (mac, IP address). When running as a long-lived service (systemd, Docker, etc.), cap retention with normal log rotation so these don't accumulate indefinitely. Keep the default --log-level info; debug logs more identifiers.

• HTTP mode uses plaintext bearer auth. Run it only on a trusted home LAN, or put a TLS-terminating reverse proxy (Caddy, nginx, …) in front of it — otherwise the token and request data are exposed in transit. stdio mode has no network exposure.

This is a self-hosted, personal/household tool with no analytics, no third-party services, and no on-disk data persistence (device state is kept in memory only). Configuration — including your bearerToken and device MACs — lives in your local config.json, which .gitignore already excludes from version control.

Testing

npm test

Covers the protocol crypto (v1/v2 encrypt-decrypt round-trips and a known-answer vector, plus envelope pack/unpack) and config-schema validation (defaults, MAC normalization, interval inheritance, duplicate-MAC and bad-value rejection).

Project layout

src/
  index.ts            entrypoint: CLI args, config load, lifecycle
  config.ts           zod schema, validation, defaults
  logger.ts           JSON-lines logger (stderr)
  gree/
    protocol.ts       AES v1/v2 + pack envelope
    commands.ts       field codes, value maps, swing maps
    device.ts         GreeDevice: scan/bind/poll/command state machine
    manager.ts        DeviceManager: registry, resolve, health summary
    types.ts          shared types
  mcp/
    server.ts         McpServer construction
    tools.ts          tool handlers
    resources.ts      per-device resources
  transport/
    stdio.ts          stdio transport
    http.ts           Streamable HTTP + legacy SSE + /healthz
  auth/
    bearer.ts         bearer-token middleware

Out of scope

• No GCloud-bridged / sub-device (bridge) topology. The reference plugin supports devices behind a bridge (mac@bridgemac); this server intentionally targets directly-addressable WiFi units only. TODO: add bridge/sub-device discovery and the subDev/sublist handshake if needed.

• No web UI.

Disclaimer

This is an independent, unofficial project. It is not affiliated with, endorsed by, or supported by GREE Electric Appliances Inc. or any of its subsidiaries. "GREE" and any related trademarks belong to their respective owners and are used here only to describe compatibility.

I built this in my free time and maintain it as a personal hobby project. It is provided as-is, without any warranty; use it at your own risk. It controls real heating/cooling hardware, so test carefully in your own environment.

GDPR / data protection

This is a self-hosted, personal/household tool. It runs entirely on your own machine/LAN, has no analytics or third-party services, makes no external network calls, and persists nothing to disk (device state is kept in memory; your bearerToken and device MACs live only in your local config.json). The only personal-data-adjacent values it handles are device identifiers (MAC and LAN IP addresses), which may appear in logs.

Used for your own home, this typically falls under the GDPR "purely personal or household activity" exemption (Art. 2(2)(c), Recital 18), meaning the GDPR generally does not apply. If you instead deploy it in a context where you process other people's data (e.g. a workplace, rental property, or any commercial setting), you are the data controller and are solely responsible for your own GDPR compliance, including transport security, log retention, transparency, and any required legal basis.

Any compliance commentary, scan, or assessment associated with this project is a preliminary, informational aid only — it is not legal advice and is not a substitute for a qualified legal audit. The authors accept no liability for how the software is deployed or used.