Shelly Smart Home

shelly-mcp

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

面向整个 Shelly 智能家居生态系统的 MCP 服务——可通过任何 MCP 客户端（Claude Desktop、Claude Code、Cursor 等）读取、控制和自动化各代 Shelly 设备（Gen1 → Gen4；BLU 可通过其网关或通用 RPC 引擎使用，专用 BLU 工具已列入路线图）。本地优先（零速率限制、约 10 ms 延迟、完整 API），并在无法通过局域网访问时回退到云端。

⚠️ 非官方社区项目。 与 Allterco Robotics / Shelly 无关联，也未获其认可或赞助。“Shelly”是其各自所有者的商标。

🚧 Alpha 阶段／开发中。 完整设计请参阅 docs/。

为什么选择它

现有的 Shelly MCP 服务只有云端版本，而且功能有限。shelly-mcp 通过统一的工具接口支持 Gen1 和 Gen2+，涵盖能源监测和自动化（计划任务、脚本、webhook、KVS），并自动发现任何设备的功能，包括本服务编写完成后发布的硬件。

安装

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

在 MCP 客户端中注册：

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

配置

自动发现（mDNS）可查找本地子网中的设备——运行 shelly_discover 即可开始使用。如需使用命名设备（“关闭厨房灯”）、访问其他子网中的设备、设置密码或启用云端回退，请创建 ~/.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

完整参考： config.example.yaml 和 docs/04-CONFIG-AND-DEPLOY.md。

哪些数据会离开你的设备

不会，除了对你自己的 Shelly 设备（位于你的局域网中）的调用，以及——仅当你启用此功能时——对你自己的 Shelly Cloud 账户的调用。不收集遥测数据，也不会主动向外发送数据。

功能（本地与云端）

	本地	云端
发现、状态、控制	✅	⚠️ 仅支持控制和状态
能源实时数据与历史数据	✅	⚠️ 仅支持实时数据
自动化（计划任务／脚本／webhook／KVS）	✅	❌

工具、资源与提示词

读取（安全）： shelly_version · shelly_discover · shelly_list_devices · shelly_get_info · shelly_get_status（已规范化）· shelly_get_config（凭据已遮蔽）· shelly_list_components · shelly_list_methods

控制（已审计）： shelly_switch_set · shelly_switch_toggle · shelly_light_set（RGBW/CCT/white）· shelly_cover_move

能源： shelly_energy_live · shelly_energy_history

通用引擎（全面覆盖）： shelly_rpc（只读）· shelly_rpc_write（修改操作，需 confirm:true + 数据丢失双重确认）

系统 / 计划任务（受控）： shelly_system_reboot|update|set_auth · shelly_schedule_list|create|update|delete

自动化（仅限 Gen2+ 本地）： shelly_kvs_*（键值存储）· shelly_webhook_*（事件→HTTP）· shelly_script_*（设备端 JS — list/get_code/create/put_code/start/stop/eval/delete，分块上传）· shelly_virtual_*（虚拟组件）。删除操作和任意代码路径（script_put_code/eval）均需通过 confirm:true 确认。

场景（确定性、命名）： shelly_scene_list|get|run|create|delete — 定义一次多设备例程，然后按名称运行（shelly_scene_run "film"），每次运行结果相同，并且可从任何客户端安排为计划任务。场景存储在 ~/.config/shelly-mcp/scenes.yaml（参见 scenes.example.yaml）；场景和计划任务仅接受普通控制方法（Switch/Light/RGB(W)/CCT/Cover），绝不接受 Script.Eval、SetAuth 或任何破坏性操作（ADR-007，docs/06-SCENES.md）。

资源： shelly://devices、shelly://device/{name}/status — 提示词： shelly_evening_scene、shelly_energy_report、shelly_diagnose

安全性： 读取操作带有 readOnlyHint；每项修改操作都会记录审计日志；通用写入工具和破坏性系统工具都需要显式设置 confirm:true，而不可逆方法（恢复出厂设置、全部擦除）还需要通过第二道 i_understand_data_loss 确认关卡 — 因此即使大模型遭到劫持，也无法悄无声息地破坏设备。

故障排除

• “设备无法访问” — 确认 IP 地址（使用 shelly_discover、路由器的客户端列表，或 Shelly 应用 → 设备 → Settings → Device information），并确认运行服务的机器与设备位于同一 LAN。在 WSL/容器中，mDNS 发现通常无法工作 — 请改为在配置文件中通过 ip 配置设备（此方式不需要 mDNS）。
• “需要身份验证” — 设备设有密码：在配置文件的设备条目下添加 password:（或设置 SHELLY_PW_<name> 环境变量）。
• 仅限云端的设备拒绝自动化工具 — 这是预期行为：Shelly Cloud API 无法管理计划任务/脚本/webhook/KVS；请在本地连接以使用这些功能。
• 配置无法加载 — 如果配置中包含机密信息，必须将权限设为 chmod 600（有意采取失败即关闭策略）。

文档

完整设计文档见 docs/（已编制索引），包括：概述、架构（含 ADR）、工具范围、安全性、场景、配置/部署、构建计划、项目日志、路线图、上线操作手册，以及完整的 Shelly API 目录。

许可证

MIT — 参见 LICENSE。