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.

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.

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.

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.

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

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.

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.