Sonoff Server

A Model Context Protocol server that lets AI agents — Claude Code, claude.ai, or any MCP client — control Sonoff smart-home devices through the eWelink Cloud API. Ask an agent to "turn on the heater" or "what's the temperature in the nursery?" and it calls a real device.

Runs as a remote MCP connector over HTTPS with full OAuth 2.0, so it can be attached to hosted AI clients, not just local ones.

Architecture

AI client (Claude Code / claude.ai)
      │  HTTPS + OAuth 2.0 (Authorization Code + PKCE)
      ▼
  reverse proxy  ──▶  sonoff-mcp (FastMCP, streamable-http)
                            │  HTTPS
                            ▼
                    eWelink Cloud API (CoolKit Open Platform v2)
                            │
                            ▼
                    Sonoff devices (THR316D, MINIR4, SV, BASICR2, …)

• Transport — streamable-http (FastMCP), fronted by a reverse proxy for TLS
• Auth — OAuth 2.0 Authorization Code + PKCE between the AI client and the server
• Upstream — eWelink Cloud API v2 with its own OAuth token flow
• SDK — FastMCP (mcp[cli]), Python 3.12+, aiohttp

Tools

Tool	Description
list_devices	All devices with live state (on/off, online, temp/humidity for thermostats)
get_device	Detailed device info (model, firmware, power, thermostat mode)
switch_device	Turn a device on/off (disables auto mode on thermostats)
get_sensor_data	Current temperature and humidity from a sensor/thermostat
set_thermostat	Set thermostat mode (heat / cool / dry / off) with thresholds

Devices are addressed by name (partial, case-insensitive match) or device ID, so an agent can act on "living room lamp" without knowing internal identifiers.

Running

cp .env.example .env      # eWelink app + MCP OAuth credentials
docker compose up -d
# then visit /ewelink/setup once to authorize your eWelink account

Configuration (.env.example):

• EWELINK_APP_ID / EWELINK_APP_SECRET — register at dev.ewelink.cc
• EWELINK_REGION — eWelink data center region (eu, us, as, cn)
• MCP_CLIENT_ID / MCP_CLIENT_SECRET — OAuth credentials for the MCP client
• SERVER_URL — public base URL the connector is served from

Notes

• Used in production as the smart-home action layer behind an AI phone assistant — the LLM calls these tools to control devices from a phone call or SMS.
• The server capability-detects each device from its eWelink parameters, so switches, thermostats, and sensors are handled through a single unified model.