shelly-mcp
Provides tools for reading, controlling, and automating Shelly smart-home devices (Gen1 through Gen4, including BLU via gateway or RPC engine). Supports device discovery, status monitoring, switch/light/cover control, energy live and history, automation (schedules, scripts, webhooks, key-value store), scenes, and system management, all locally with optional cloud fallback.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@shelly-mcp turn off the kitchen light"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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-mcpRegister 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_KEYFull 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 explicitconfirm:true, and irreversible methods (factory reset, wipe-all) need a secondi_understand_data_lossgate — 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 byipin the config file instead (that path needs no mDNS)."Auth required" — the device has a password: add
password:under the device in the config (orSHELLY_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 toolsshelly_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_discoverARead-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_historyBRead-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_liveARead-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_configARead-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_infoARead-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_statusARead-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_deleteADestructive
Delete a KVS key. Requires confirm:true. Audit-logged.
Inputs: key (required), device (required), confirm. Returns: object
shelly_kvs_getBRead-only
Get one KVS value (with its etag) by key.
Inputs: key (required), device (required). Returns: object
shelly_kvs_listBRead-only
List KVS keys (with their etags). match is a wildcard pattern (default all).
Inputs: device (required), match. Returns: object
shelly_kvs_setBIdempotent
Set a KVS key to a JSON value. Audit-logged.
Inputs: key (required), value (required), device (required). Returns: object
shelly_light_setAIdempotent
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_componentsARead-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_devicesARead-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_methodsARead-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_rpcARead-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_writeADestructive
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_createAIdempotent
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_deleteADestructive
Delete a named scene. Requires confirm:true.
Inputs: name (required), confirm. Returns: object
shelly_scene_getBRead-only
Show a scene's full definition (its ordered actions). Read-only.
Inputs: name (required). Returns: object
shelly_scene_listARead-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_createAIdempotent
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_deleteBDestructive
Delete a schedule by id. Requires confirm:true. Audit-logged.
Inputs: id (required), device (required), confirm. Returns: object
shelly_schedule_listBRead-only
List the schedules configured on a device. Local-only (cloud can't manage schedules).
Inputs: device (required). Returns: object
shelly_schedule_updateCIdempotent
Update fields of an existing schedule by id. Audit-logged.
Inputs: id (required), device (required), calls, enable, +1 more. Returns: object
shelly_script_createAIdempotent
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_deleteADestructive
Delete a script by id. Requires confirm:true. Audit-logged.
Inputs: id (required), device (required), confirm. Returns: object
shelly_script_evalADestructive
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_codeARead-only
Get a script's full source, reassembling the device's paginated GetCode.
Inputs: id (required), device (required). Returns: object
shelly_script_listBRead-only
List scripts on a device (id, name, enable, running). Local-only.
Inputs: device (required). Returns: object
shelly_script_put_codeADestructive
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_setAIdempotent
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_rebootBDestructive
Reboot a device. Requires confirm:true. Audit-logged.
Inputs: device (required), confirm, delay_ms. Returns: object
shelly_system_set_authADestructive
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_updateBDestructive
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_addAIdempotent
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_deleteADestructive
Delete a virtual component by key (<type>:<cid>). Requires confirm:true.
Inputs: key (required), device (required), confirm. Returns: object
shelly_virtual_listBRead-only
List the device's virtual (dynamic) components via Shelly.GetComponents.
Inputs: device (required). Returns: object
shelly_webhook_createBIdempotent
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_deleteADestructive
Delete a webhook by id. Requires confirm:true. Audit-logged.
Inputs: id (required), device (required), confirm. Returns: object
shelly_webhook_listBRead-only
List webhooks configured on a device. Local-only.
Inputs: device (required). Returns: object
shelly_webhook_updateBIdempotent
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
Scored across 47 tools
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.
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.
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.
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
Related MCP Connectors
MCP server wrapping the Tesla Fleet API and TeslaMate API
Syslog receiver and MCP server for homelab log intelligence.
Syslog receiver and MCP server for homelab log intelligence.
Related MCP Servers
- AlicenseBqualityDmaintenanceMCP server for full Home Assistant control, enabling AI agents to manage dashboards, automations, files, apps, entities, and more via REST API, WebSocket, and SSH.66151 npmMIT
- AlicenseNot gradedqualityDmaintenanceA 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
- FlicenseNot gradedqualityCmaintenanceMCP server for controlling Somfy TaHoma devices locally via the box's API, without cloud dependency.-
- AlicenseAqualityDmaintenanceMCP 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.8MIT