Shelly Smart Home MCP server

shelly-mcp

mcp-name: io.github.Buggy1111/shelly-mcp

MCP server for the entire Shelly smart-home ecosystem — read, control, and automate Shelly devices of every generation (Gen1 → Gen4; BLU via its gateway or the generic RPC engine, dedicated BLU tools are on the roadmap) from any MCP client (Claude Desktop, Claude Code, Cursor, …). Local-first (zero rate-limit, ~10 ms, full API), with cloud fallback for off-LAN access.

⚠️ Unofficial community project. Not affiliated with, endorsed by, or sponsored by Allterco Robotics / Shelly. "Shelly" is a trademark of its respective owner.

🚧 Alpha / in development. See docs/ for the full design.

Why

The only existing Shelly MCP servers are cloud-only and minimal. shelly-mcp unifies Gen1 and Gen2+ behind one tool surface, covers energy monitoring and automation (schedules, scripts, webhooks, KVS), and auto-discovers any device's capabilities — including hardware released after this server was written.

Install

uvx shelly-mcp          # or: pip install shelly-mcp

Register in your MCP client:

{ "mcpServers": { "shelly": { "command": "uvx", "args": ["shelly-mcp"] } } }

Configure

Auto-discovery (mDNS) finds devices on your local subnet — shelly_discover and you're running. For named devices ("turn off the kitchen"), devices on other subnets, passwords, or the cloud fallback, create ~/.config/shelly-mcp/config.yaml (chmod 600):

devices:
  televize:
    ip: 192.168.0.101
    location: obývák            # lets "turn off the living room" work
    # password: "..."           # only if the device has auth (or env SHELLY_PW_televize)
cloud:
  enabled: false                # optional off-LAN fallback
  # auth_key via env SHELLY_CLOUD_AUTH_KEY

Full reference: config.example.yaml and docs/04-CONFIG-AND-DEPLOY.md.

What data leaves your machine

None, beyond the calls to your own Shelly devices (on your LAN) and — only if you enable it — your own Shelly Cloud account. No telemetry, no phone-home.

Capabilities (local vs cloud)

Tools, resources & prompts

Read (safe): shellyversion · shellydiscover · shellylistdevices · shellygetinfo · shellygetstatus (normalized) · shellygetconfig (credentials masked) · shellylistcomponents · shellylistmethods

Control (audited): shellyswitchset · shellyswitchtoggle · shellylightset (RGBW/CCT/white) · shellycovermove

Energy: shellyenergylive · shellyenergyhistory

Generic engine (total coverage): shellyrpc (read-only) · shellyrpc_write (mutations, confirm:true + data-loss double-gate)

System / schedules (gated): shellysystemreboot|update|setauth · shellyschedule_list|create|update|delete

Automation (Gen2+ local-only): shellykvs (key-value store) · shellywebhook (event→HTTP) · shellyscript (on-device JS — list/getcode/create/putcode/start/stop/eval/delete, chunked upload) · shellyvirtual (virtual components). Deletes + arbitrary-code paths (scriptputcode/eval) are confirm:true-gated.

Shortened. The full README is on GitHub.