Skip to main content
Glama
shelly-mcp

shelly-mcp

by Buggy1111

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.

Related MCP server: govee-mcp

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)

Local

Cloud

Discovery, status, control

✅

⚠️ control + status only

Energy live + history

✅

⚠️ live only

Automation (schedules/scripts/webhooks/KVS)

✅

❌

Tools, resources & prompts

Read (safe): shelly_version · shelly_discover · shelly_list_devices · shelly_get_info · shelly_get_status (normalized) · shelly_get_config (credentials masked) · shelly_list_components · shelly_list_methods

Control (audited): shelly_switch_set · shelly_switch_toggle · shelly_light_set (RGBW/CCT/white) · shelly_cover_move

Energy: shelly_energy_live · shelly_energy_history

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

System / schedules (gated): shelly_system_reboot|update|set_auth · shelly_schedule_list|create|update|delete

Automation (Gen2+ local-only): shelly_kvs_* (key-value store) · shelly_webhook_* (event→HTTP) · shelly_script_* (on-device JS — list/get_code/create/put_code/start/stop/eval/delete, chunked upload) · shelly_virtual_* (virtual components). Deletes + arbitrary-code paths (script_put_code/eval) are confirm:true-gated.

Scenes (deterministic, named): shelly_scene_list|get|run|create|delete — define a multi-device routine once and run it by name (shelly_scene_run "film"), identical every time and schedulable from any client. Stored in ~/.config/shelly-mcp/scenes.yaml (see scenes.example.yaml); scenes and schedules accept only plain control methods (Switch/Light/RGB(W)/CCT/Cover) — never Script.Eval, SetAuth, or anything destructive (ADR-007, docs/06-SCENES.md).

Resources: shelly://devices, shelly://device/{name}/status — Prompts: shelly_evening_scene, shelly_energy_report, shelly_diagnose

Safety: reads are readOnlyHint; every mutation is audit-logged; the generic write tool and destructive system tools require explicit confirm:true, and irreversible methods (factory reset, wipe-all) need a second i_understand_data_loss gate — so even a hijacked LLM can't silently destroy a device.

Troubleshooting

  • "Device unreachable" — confirm the IP (shelly_discover, your router's client list, or the Shelly app → device → Settings → Device information), and that the machine running the server is on the same LAN. In WSL/containers, mDNS discovery usually doesn't work — configure devices by ip in the config file instead (that path needs no mDNS).

  • "Auth required" — the device has a password: add password: under the device in the config (or SHELLY_PW_<name> env var).

  • Cloud-only device refuses automation tools — expected: the Shelly Cloud API can't manage schedules/scripts/webhooks/KVS; connect locally for those.

  • Config refuses to load — if it contains a secret, it must be chmod 600 (deliberate, fail-closed).

Docs

Full design in docs/ (indexed): overview, architecture (+ADRs), tool surface, security, scenes, config/deploy, build plan, project log, roadmap, the launch runbook, and the complete Shelly API catalog.

License

MIT — see LICENSE.

Available Tools

47 tools
shelly_cover_moveA

Move a roller/cover: action is open|close|stop, or pass position (0-100) to go to it.

Returns the post-action CoverState. Audit-logged.

Inputs: action (required), device (required), channel, position. Returns: object

shelly_discoverA
Read-only

Discover Shelly devices on the LAN via mDNS, merged with the cloud account list.

timeout_s is the mDNS browse window. Set use_cloud=false to skip the cloud list (LAN-only). Safe, read-only; returns lightweight identities (probe for detail).

Inputs: timeout_s, use_cloud. Returns: object

shelly_energy_historyB
Read-only

Best-effort energy history: lifetime totals plus any per-minute series the device exposes in its status; notes when richer history needs a local connection.

Detailed historical queries (Pro 3EM EMData/CSV, Gen1 em_data.csv) land with the local backends (M2) — over cloud only totals + recent by-minute are available.

Inputs: device (required), channel. Returns: object

shelly_energy_liveA
Read-only

Live power/energy per channel: power_w, voltage, current, pf, freq, totals.

None where a device can't report it (e.g. Gen1 plugs have no voltage/current). Pass channel to narrow to one. Safe, read-only.

Inputs: device (required), channel. Returns: object

shelly_get_configA
Read-only

Get a device's configuration, with credential fields masked as *** (Gen1 /settings returns Wi-Fi/MQTT secrets in the clear — they must not reach the model). Local-first — the Shelly Cloud API can't expose config, so this returns an actionable error for cloud-only devices.

Inputs: device (required), component. Returns: object

shelly_get_infoA
Read-only

Identify one device (generation, model, firmware, online state, capabilities).

device is a device id or a configured name. Safe, read-only.

Inputs: device (required). Returns: object

shelly_get_statusA
Read-only

Get a device's normalized live status (Gen1/Gen2/Cloud folded into one shape).

Returns canonical channels/lights/covers plus the raw per-generation payload. Pass component (e.g. "switch:0") to narrow to a single component. Safe, read-only.

Inputs: device (required), component. Returns: object

shelly_kvs_deleteA
Destructive

Delete a KVS key. Requires confirm:true. Audit-logged.

Inputs: key (required), device (required), confirm. Returns: object

shelly_kvs_getB
Read-only

Get one KVS value (with its etag) by key.

Inputs: key (required), device (required). Returns: object

shelly_kvs_listB
Read-only

List KVS keys (with their etags). match is a wildcard pattern (default all).

Inputs: device (required), match. Returns: object

shelly_kvs_setB
Idempotent

Set a KVS key to a JSON value. Audit-logged.

Inputs: key (required), value (required), device (required). Returns: object

shelly_light_setA
Idempotent

Set a light/dimmer/RGB(W)/CCT channel (Gen1 /color,/light ↔ Gen2 Light/RGB/RGBW/CCT.Set).

Only the provided fields are changed. brightness 0-100, rgb three 0-255 values, temp_k white colour temperature. Returns the post-action LightState. Audit-logged.

Inputs: device (required), on, rgb, white, +4 more. Returns: object

shelly_list_componentsA
Read-only

List the component keys present on a device (e.g. ['switch:0', 'input:0']).

Safe, read-only. Use this to discover what a specific device exposes before reading status or controlling it.

Inputs: device (required). Returns: object

shelly_list_devicesA
Read-only

List every Shelly device known to this server (configured + cloud account).

Safe, read-only. Returns each device's canonical identity (id, name, generation, model, online state) — the starting point before any status or control call.

Inputs: no named parameters. Returns: object

shelly_list_methodsA
Read-only

List the RPC methods a device supports (Gen2+ Shelly.ListMethods).

Returns an actionable error on Gen1/cloud where the device can't enumerate methods.

Inputs: device (required). Returns: object

shelly_rpcA
Read-only

Call any read-only RPC method (*.Get*/*.List*/*.Check*) on a device.

Mutating methods are refused here — use shelly_rpc_write. The method name is classified server-side; unknown methods are treated as writes and rejected.

Inputs: device (required), method (required), params. Returns: object

shelly_rpc_writeA
Destructive

Call any mutating RPC method. Requires confirm:true; audit-logged.

Read methods are rejected (use shelly_rpc). Destructive methods (factory reset, wipe-all, reset-wifi) need a second gate: params.i_understand_data_loss = true.

Inputs: device (required), method (required), params, confirm. Returns: object

shelly_scene_createA
Idempotent

Define (save) a named scene from an ordered list of {device, method, params}.

Every method must be a non-destructive mutating method; every device must be known. Fails if the name already exists unless overwrite=true. Prefer absolute Set methods over Toggle so the scene is safe to run twice (you'll get a warning otherwise).

Inputs: name (required), actions (required), overwrite, description. Returns: object

shelly_scene_deleteA
Destructive

Delete a named scene. Requires confirm:true.

Inputs: name (required), confirm. Returns: object

shelly_scene_getB
Read-only

Show a scene's full definition (its ordered actions). Read-only.

Inputs: name (required). Returns: object

shelly_scene_listA
Read-only

List defined scenes (name, description, action count). Read-only.

Inputs: no named parameters. Returns: object

shelly_scene_runA

Run a named scene: attempt every action in order, report per-action results.

Best-effort and sequential — a failing action does not abort the rest. status is ok (all succeeded), partial (some failed), or failed (none succeeded). A partial run can simply be re-run later to finish it (scenes use absolute states, so re-running is safe). Every action is audit-logged.

Inputs: name (required). Returns: object

shelly_schedule_createA
Idempotent

Create a schedule: timespec + calls (1-5 × {method, params}).

timespec: cron "sec min hour day month dow" (e.g. "0 0 22 * * MON-THU"; 5 or 7 fields also accepted), a shorthand (@daily), or sun-relative "@sunset", "@sunset+30m", "@sunrise-1h * * MON-FRI" (offset max ±12 h; the device needs its location set). Validates the timespec, ≤5 calls, the ≤20-per-device limit, and each call's method. Audit-logged.

Inputs: calls (required), device (required), timespec (required), enable. Returns: object

shelly_schedule_deleteB
Destructive

Delete a schedule by id. Requires confirm:true. Audit-logged.

Inputs: id (required), device (required), confirm. Returns: object

shelly_schedule_listB
Read-only

List the schedules configured on a device. Local-only (cloud can't manage schedules).

Inputs: device (required). Returns: object

shelly_schedule_updateC
Idempotent

Update fields of an existing schedule by id. Audit-logged.

Inputs: id (required), device (required), calls, enable, +1 more. Returns: object

shelly_script_createA
Idempotent

Create an empty script (optionally named). Returns its id. Audit-logged.

Use shelly_script_put_code to give it code (that step is confirm-gated).

Inputs: device (required), name. Returns: object

shelly_script_deleteA
Destructive

Delete a script by id. Requires confirm:true. Audit-logged.

Inputs: id (required), device (required), confirm. Returns: object

shelly_script_evalA
Destructive

Evaluate an expression inside a running script. Arbitrary code → confirm:true.

Returns the stringified result. Audit-logged.

Inputs: id (required), code (required), device (required), confirm. Returns: object

shelly_script_get_codeA
Read-only

Get a script's full source, reassembling the device's paginated GetCode.

Inputs: id (required), device (required). Returns: object

shelly_script_listB
Read-only

List scripts on a device (id, name, enable, running). Local-only.

Inputs: device (required). Returns: object

shelly_script_put_codeA
Destructive

Upload code into a script (chunked). Arbitrary code on the device → confirm:true.

append=false replaces the script body; true appends. Large code is split into ≤1 KB chunks automatically. Audit-logged.

Inputs: id (required), code (required), device (required), append, +1 more. Returns: object

shelly_script_startB

Start a script by id. Returns was_running. Audit-logged.

Inputs: id (required), device (required). Returns: object

shelly_script_stopB

Stop a script by id. Returns was_running. Audit-logged.

Inputs: id (required), device (required). Returns: object

shelly_switch_setA
Idempotent

Turn a switch/relay channel on or off (optionally auto-revert after N seconds).

Returns the post-action ChannelState. Audit-logged.

Inputs: on (required), device (required), channel, toggle_after_s. Returns: object

shelly_switch_toggleB

Toggle a switch/relay channel. Returns the post-action ChannelState. Audit-logged.

Inputs: device (required), channel. Returns: object

shelly_system_rebootB
Destructive

Reboot a device. Requires confirm:true. Audit-logged.

Inputs: device (required), confirm, delay_ms. Returns: object

shelly_system_set_authA
Destructive

Enable/rotate the device login password (≥12 chars). Requires confirm:true.

The password is write-only — never returned, and redacted in the audit log.

Inputs: device (required), password (required), confirm. Returns: object

shelly_system_updateB
Destructive

Trigger a firmware update (channel = stable|beta). Requires confirm:true.

Inputs: device (required), channel, confirm. Returns: object

shelly_versionA

Return the shelly-mcp server version (health check).

Inputs: no named parameters. Returns: object

shelly_virtual_addA
Idempotent

Add a virtual component of type (boolean/number/text/enum/button/group).

Optional config and id (200-299). Returns the new component id. Audit-logged.

Inputs: type (required), device (required), id, config. Returns: object

shelly_virtual_deleteA
Destructive

Delete a virtual component by key (<type>:<cid>). Requires confirm:true.

Inputs: key (required), device (required), confirm. Returns: object

shelly_virtual_listB
Read-only

List the device's virtual (dynamic) components via Shelly.GetComponents.

Inputs: device (required). Returns: object

shelly_webhook_createB
Idempotent

Create a webhook: event (e.g. 'switch.on'), cid component id, urls 1-5.

Optional condition (JS expression) and repeat_period (seconds; 0=always, negative=once). Audit-logged.

Inputs: cid (required), urls (required), event (required), device (required), +4 more. Returns: object

shelly_webhook_deleteA
Destructive

Delete a webhook by id. Requires confirm:true. Audit-logged.

Inputs: id (required), device (required), confirm. Returns: object

shelly_webhook_listB
Read-only

List webhooks configured on a device. Local-only.

Inputs: device (required). Returns: object

shelly_webhook_updateB
Idempotent

Update fields of an existing webhook by id. Audit-logged.

Inputs: id (required), device (required), name, urls, +3 more. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 47 tools

    Disambiguation4/5

    Almost every tool has a distinct resource+action target, and descriptions sharply differentiate read vs. write (shelly_rpc vs shelly_rpc_write) and info vs. status vs. config. The only real overlap is shelly_list_devices vs shelly_discover (both enumerate devices), though the LAN-mDNS vs. known/cloud distinction is spelled out. Minor boundary blurring keeps it just under perfect.

    Naming Consistency4/5

    Uniform shelly_ prefix and snake_case throughout, with domain-grouped names (scene_, schedule_, script_, kvs_, webhook_, virtual_) that are highly predictable. The one deviation is the control group using noun_verb (switch_set, light_set, cover_move) vs. verb_noun elsewhere (list_components, get_status), which is consistent within its group but not across the whole set.

    Tool Count3/5

    47 tools is heavy (well above the ~15 ideal) and will burden selection, but the surface genuinely spans many independent subsystems — devices, KVS, scenes, schedules, scripts, webhooks, virtual components, energy, and system ops — each legitimately needing CRUD. It is large but not a mismatch the way a 50+ grab-bag would be.

    Completeness5/5

    Near-complete lifecycle coverage: CRUD for KVS, schedules, webhooks, scripts, and virtual components; create/run/delete for scenes (with overwrite covering update); device discovery, info, status, config, energy live+history, and system reboot/update/auth. The read/write RPC escape hatches (shelly_rpc, shelly_rpc_write) close any residual gaps, leaving no obvious dead ends.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      MCP server for full Home Assistant control, enabling AI agents to manage dashboards, automations, files, apps, entities, and more via REST API, WebSocket, and SSH.
      66
      151 npm
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A LAN-first, cloud-fallback MCP server for controlling Govee smart devices by name. It enables AI agents or MCP clients to manage lights, plugs, and appliances with commands like power, brightness, color, and scenes.
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      MCP server for controlling Somfy TaHoma devices locally via the box's API, without cloud dependency.
      -
    • A
      license
      A
      quality
      D
      maintenance
      MCP server for Hubitat Elevation hubs that controls devices via the Maker API, with optional gated access to undocumented admin routes, supporting device listing, command sending, virtual device and hub variable automation for Rule Machine, and hub management features.
      8
      MIT