GREE MCP Server

LAN-local MCP server for controlling GREE / EWPE WiFi air conditioners over their native UDP protocol. No cloud. stdio + HTTP transports.

AModel Context Protocol(MCP) server that controlsGREE / EWPE-compatible WiFi air conditionersdirectly 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 oneibenp/homebridge-gree-airconditionerandtomikaa87/gree-remote.

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

JSON file validated withzod. 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).

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

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

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

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

Initialize (note the requiredAcceptheader 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>

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}}}'

# 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"}'

The image is multi-stage and runs as the non-rootnodeuser, 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 hostis the simplest way to give the container that on Linux; otherwise set each device'saddressexplicitly and ensure UDP/7000 routing to the units works from the container network.

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

- Logs are JSON lines onstderr(stdout is reserved for the MCP channel in stdio mode), including devicemac,action, andoutcome.
- The bearer token and all AES/device keys arenever 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;debuglogs more identifiers.
- HTTP mode uses plaintext bearer auth.Run it only on atrusted 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.stdiomode 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 yourbearerTokenand device MACs — lives in your localconfig.json, which.gitignorealready excludes from version control.

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).

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

- 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 thesubDev/sublisthandshake if needed.
- No web UI.

This is an independent, unofficial project. It isnot 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 providedas-is, without any warranty; use it at your own risk. It controls real heating/cooling hardware, so test carefully in your own environment.

This is aself-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; yourbearerTokenand device MACs live only in your localconfig.json). The only personal-data-adjacent values it handles aredevice 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 controllerand 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 apreliminary, 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.

Manage your WhatsApp, SMS and Phone Calls using a single MCP connector

Connect to any function, any language, across network boundaries using AgentRPC.

Access your meeting transcripts, summaries, and action items from any AI assistant.

Connect Claude, ChatGPT, and other AI tools to your Granola meeting notes via MCP. Query your notes, search transcripts, and get meeting insights in your favorite AI assistants.

Build with the Kudosity API to send SMS and MMS. Access developer docs, API references and live testing tools to send messages, manage contact lists, configure webhooks and more.

Send SMS, WhatsApp, and RCS messages programmatically with DLT compliance. Manage contacts, schedule campaigns, and track delivery reports.

Interact with Twilio APIs to send messages, manage phone numbers, configure your account, and more.

The VoIPstudio MCP server gives compatible AI assistants secure access to authorised VoIPstudio account data, including recordings, call detail records, live calls and voicemails in order to query call activity, analyse patterns, identify agent performance issues and generate QA or operations reports in plain English.

A bridge server connecting Agent Communication Protocol (ACP) agents with Model Context Protocol (MCP) clients.