Shelly Smart Home

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.

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

List the RPC methods a device supports (Gen2+ ``Shelly.ListMethods``). Returns an actionable error on Gen1/cloud where the device can't enumerate methods.

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.

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.

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

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

Enable/rotate the device login password (≥12 chars). Requires ``confirm:true``. The password is write-only — never returned, and redacted in the audit log.

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

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.

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

List webhooks configured on a device. Local-only.

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.

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

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

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

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

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.

Identify one device (generation, model, firmware, online state, capabilities). ``device`` is a device id or a configured name. Safe, 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.

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.

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.

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

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.

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

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

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

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

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

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.

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

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

Evaluate an expression inside a running script. **Arbitrary code** → ``confirm:true``. Returns the stringified result. Audit-logged.

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

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

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

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

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.

Delete a named scene. Requires ``confirm:true``.

Turn a switch/relay channel on or off (optionally auto-revert after N seconds). Returns the post-action ``ChannelState``. Audit-logged.

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

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.

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.

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

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

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

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