Shelly Smart Home

shelly-mcp

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

Shelly スマートホームエコシステム全体に対応する MCP サーバー — あらゆる世代の Shelly デバイス（Gen1 → Gen4。BLU はゲートウェイまたは汎用 RPC エンジン経由で対応。専用 BLU ツールはロードマップに掲載）を、あらゆる MCP クライアント（Claude Desktop、Claude Code、Cursor、…）から読み取り、操作、自動化できます。ローカルファースト（レート制限なし、約 10 ms、API 全機能に対応）で、LAN 外からのアクセスにはクラウドにフォールバックします。

⚠️ 非公式のコミュニティプロジェクトです。 Allterco Robotics / Shelly とは提携、推奨、後援関係にありません。「Shelly」は各所有者の商標です。

🚧 アルファ版／開発中です。 設計の全容については docs/ をご覧ください。

導入する理由

既存の Shelly MCP サーバーは、クラウド専用で機能も最小限です。shelly-mcp は Gen1 と Gen2 以降を 1 つのツール群に統合し、エネルギー監視と自動化（スケジュール、スクリプト、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 デバイス（LAN 上）への呼び出しと、有効にした場合に限りご自身の 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 による第 2 のゲートが必要なため、LLM が乗っ取られてもデバイスを気付かれないまま破壊することはできません。

トラブルシューティング

• 「Device unreachable」 — IP アドレスを確認してください（shelly_discover、ルーターのクライアント一覧、または Shelly アプリ → デバイス → 設定 → デバイス情報）。また、サーバーを実行しているマシンが同じ LAN に接続されていることを確認してください。WSL／コンテナーでは、通常 mDNS による検出は機能しません。代わりに設定ファイルでデバイスを ip によって設定してください（この方法では mDNS は不要です）。
• 「Auth required」 — デバイスにパスワードが設定されています。設定ファイルのデバイス項目に password: を追加するか、環境変数 SHELLY_PW_<name> を設定してください。
• クラウド専用デバイスで自動化ツールが拒否される — 想定どおりの動作です。Shelly Cloud API ではスケジュール／スクリプト／Webhook／KVS を管理できません。これらを使用するにはローカル接続してください。
• 設定を読み込めない — 秘密情報が含まれる場合は、chmod 600 を設定する必要があります（意図的にフェイルクローズする仕様です）。

ドキュメント

設計の全容は docs/ にまとめられています（項目別索引あり）。概要、アーキテクチャ（ADR を含む）、ツール一覧、セキュリティ、シーン、設定／デプロイ、ビルド計画、プロジェクトログ、ロードマップ、リリース手順書、Shelly API の完全なカタログを掲載しています。

ライセンス

MIT — LICENSE を参照してください。