Yeelight IoT MCP Server

Yeelight IoT MCP

简体中文

公式リポジトリとミラー

GitHub は、課題、コントリビューション、CI、リリースの正式なソースです。GitHub に安定してアクセスできないユーザー向けに、読み取り専用ミラーとして Gitee と GitCode を利用できます。また、グローバルな予備ソースとして GitLab.com も利用できます。アクセス可能なソースからクローンできますが、課題の報告や変更のコントリビューションは GitHub で行ってください。

重要

Yeelight MCP を初めてお使いですか？このリポジトリを個別にインストールするのではなく、Yeelight MCP のセットアップを 1 つ利用してください。

セットアップでは、このライブ状態／制御サービスと Yeelight Metadata MCP をまとめて構成します。このリポジトリは、専用のサーバー、エンドポイント、ツールに関する開発者向けリファレンスとして引き続き利用できます。

初心者向けの手順全体については、Yeelight 公式英語チュートリアルに従ってください。または、簡体字中国語のチュートリアルを開いてください。

Yeelight Cloud MCP スイート

このリポジトリは、Yeelight 公式クラウド MCP スイートのうち、集中的な制御を担う部分です。一般ユーザーは、同じセットアップを通じて、独立してデプロイされた 2 つのサービスを 1 つの機能グループとして利用できます。

サーバー	スイートでの役割	主な機能
Metadata MCP	ホームの把握と保護された管理。	幅広い探索と保護された管理ワークフロー、複数リージョンの認証、リクエスト単位のホーム選択。
IoT MCP	ライブ状態と集中的な制御。	トポロジーとライブ状態への直接アクセス、control_node、execute_scene。

推奨する構成： Yeelight MCP のセットアップを 1 つ実行すると、2 回目のインストールやスキャンを行わずに両方のサービスを利用できます。

どの MCP を使えばよいですか？

必要なもの	推奨される利用方法
Yeelight MCP との初回連携	yeelight-home setup --mode mcp --mcp-source cloud で Yeelight MCP スイート全体を構成します
ホーム、部屋、デバイス、グループ、パネル、シーン、自動化、お気に入り、メンテナンス、アカウントのワークフロー	Yeelight Metadata MCP
複数リージョンの認証とリクエスト単位のホーム選択	Yeelight Metadata MCP。必要に応じて Yeelight Home と組み合わせて構成してください
control_node または execute_scene に依存する既存の連携	Yeelight IoT MCP を引き続き使用してください
集中的な直接制御、ライブ状態、シーン実行の開発またはトラブルシューティング	このリポジトリのサーバーとツールのドキュメントを使用してください

Yeelight AI における位置付け

yeelight-home は、推奨されるインストール、QR コードでのサインイン、クライアント構成のフローを提供します。一般ユーザーには、Yeelight MCP 専用クライアントはクラウドセットアップを 1 回実行して Yeelight MCP スイート全体を利用し、完全版の yeelight-smart-home Skill を使用することを推奨します。クラウドサービスは、その後ローカル Runtime から独立して動作します。

簡単に言うと、一般ユーザーがこのサーバーを個別にインストールする必要はありません。統合セットアップに含まれており、既存の連携や専用の連携からは引き続き個別にアクセスできます。Yeelight Home やどちらの Skill に対しても、依存関係ではありません。

既存および専門分野向けの IoT MCP 統合

Yeelight IoT MCP は、Yeelight Pro のホームに特化した公式の Model Context Protocol サーバーです。MCP クライアントでホーム、エリア、部屋、デバイス、グループ、シーンを検出し、現在の機能を読み取り、安全なデバイス制御を準備して、確認済みの制御やシーンを実行できます。既存および専門分野向けの統合については、以下のドキュメントを引き続き正式なリファレンスとしてご利用ください。

スイートの概要と推奨されるデフォルト設定については、 Yeelight Metadata MCP に戻ってください。

機能

• Streamable HTTP MCP トランスポート。
• 公式ホスト型エンドポイントまたはセルフホスト可能なソースデプロイ。
• トポロジーの検出、デバイス制御、シーン実行に対応する 8 つのツール。
• エリア、部屋、デバイス、グループ、シーンの一覧でカーソルページネーションに対応。
• デバイス制御とシーン実行はデフォルトでドライラン。
• 制御プランの機密情報を除去し、副作用の実行には明示的な確認を要求。

要件

• ローカルデプロイには Python 3.10 以降。
• ドキュメントに記載されたローカルワークフローには uv。
• Yeelight Authorization トークン。Region と House ID は任意です。

推奨：Yeelight Home でサインインと設定を完了する

npm install --global yeelight-home
yeelight-home setup --lang en-US --mode mcp --agent cursor --mcp-source cloud --yes

コマンドを実行すると QR コードが表示されます。Yeelight Pro アプリの Home で、右上の + をタップし、MCP Authorization を選択してスキャンしてください。Pro のホームが 1 つの場合は自動的に選択され、複数ある場合は名前で表示されます。クラウドモードでは、ローカルの認証情報プロキシを通じて Metadata MCP と IoT MCP をまとめて設定するため、AI クライアントの設定に Authorization をコピーする必要はありません。トークンを手動で設定する方法も、高度な互換性のための手段として引き続き利用できます。

ホスト型サービス

公式の Streamable HTTP エンドポイントを使用します。

https://api.yeelight.com/apis/mcp_server/v1/mcp

必須のリクエストヘッダー：

Authorization: <YOUR_AUTHORIZATION>

省略可能なヘッダーは Yeelight-Region と House-Id です。サーバーは、生のトークンと Bearer を先頭に付けた値のどちらも受け付けます。Region が省略された場合、JWT の Region クレームによって、完全なトークンの検証前に公式エンドポイントが選択されます。House ID が省略された場合、サーバーはその Region 内の最初の Pro ホームを選択します。ユーザーが Client ID を設定する必要はありません。IoT の上流への呼び出しでは、必要に応じて検証済み JWT から Client ID を取得します。JWT から取得できない場合は、開発用の Region では dev、cn、sg、us、eu では iot-app にフォールバックします。

ローカル開発

git clone https://github.com/Yeelight/yeelight-iot-mcp.git
cd yeelight-iot-mcp

uv sync --extra test
YEELIGHT_IOT_MCP_RUNTIME_ENV=local \
YEELIGHT_IOT_MCP_NACOS_ENABLED=false \
PYTHONPATH=src \
uv run uvicorn main:streamable_http_app --host 127.0.0.1 --port 9000

ローカル MCP URL は http://127.0.0.1:9000/mcp です。ローカルデプロイでも Yeelight のクラウド API を使用するため、オフラインゲートウェイではありません。バインドアドレスや実行環境にかかわらず、すべてのリクエストに Authorization ヘッダーを明示的に指定する必要があります。このサービスがオペレーターの CLI Profile を読み取ることはありません。テストでは、明示的に分離された認証情報プロバイダーを使用できます。公開プロジェクトでは Nacos 登録はデフォルトで無効になっており、環境変数を使って明示的に有効化できます。

MCP クライアントの設定

{
  "mcpServers": {
    "yeelight-iot": {
      "url": "https://api.yeelight.com/apis/mcp_server/v1/mcp",
      "headers": {
        "Authorization": "<YOUR_AUTHORIZATION>"
      }
    }
  }
}

設定を変更した後は MCP クライアントを再起動し、 tools/list に Yeelight のツールが返されることを確認してください。

ツール

ツール	用途	副作用
get_currnet_house_info	選択中のホームを読み取ります。互換性のため、スペルミスをそのまま維持しています。	読み取りのみ
get_areas	カーソルページネーションでエリアを一覧表示します。	読み取りのみ
get_rooms	カーソルページネーションで部屋を一覧表示します。	読み取りのみ
get_devices	すべてのデバイスを一覧表示するか、部屋で絞り込みます。	読み取りのみ
get_groups	すべてのグループを一覧表示するか、部屋で絞り込みます。	読み取りのみ
get_scenes	カーソルページネーションでシーンを一覧表示します。	読み取りのみ
control_node	ノードのプロパティコマンドをプレビューまたは実行します。	デフォルトでドライラン
execute_scene	シーンをプレビューまたは実行します。	デフォルトでドライラン

リクエスト例と操作ルールについては、使用ガイドをお読みください。 クライアントとデプロイの詳細については、統合ガイドをお読みください。

安全モデル

control_node と execute_scene のデフォルトは dryRun=true です。実際に操作するには、dryRun=false と confirmSideEffect=true の両方が必要です。呼び出し側では、次の手順を実施してください。

1. 読み取りツールを使って、名前を現在の ID に解決します。
2. 対象がサポートするプロパティと演算子を確認します。
3. ドライランの計画を生成してレビューします。
4. 呼び出し元のアプリケーションでユーザーの確認を得ます。
5. 1 回だけ実行し、可能であれば結果の状態を照会します。

制御プロパティ rs は現在の安全ポリシーによりブロックされています。書き込みやシーンの実行に失敗した場合、むやみに再試行しないでください。

設定

ローカル環境へのデプロイで使用する一般的な環境変数：

変数	デフォルト値	用途
YEELIGHT_IOT_MCP_API_BASE_URL	https://api.yeelight.com	Yeelight API のオリジン
YEELIGHT_IOT_MCP_DEFAULT_REGION	cn	不透明なトークンに使用するフォールバック Region
YEELIGHT_IOT_MCP_BIND_HOST	ローカル／テスト環境では 127.0.0.1	バインドアドレス。本番環境ではデフォルトで 0.0.0.0
YEELIGHT_IOT_MCP_PATH	/mcp	Streamable HTTP パス
YEELIGHT_IOT_MCP_HTTP_TIMEOUT	15	アップストリームのタイムアウト（秒）
YEELIGHT_IOT_MCP_FETCH_NODES_MAX_SIZE	300	リストページの最大サイズ
YEELIGHT_IOT_MCP_NACOS_ENABLED	false	オプションのサービス登録を有効化
YEELIGHT_IOT_MCP_LOG_DIR	./logs/yeelight-online-iot-mcp-server	ログディレクトリ

テスト

uv run --extra test pytest -q

テストでは、JWT クレームの処理、複数 Region へのルーティング、ローカル Profile の分離、Pro のフォールバック処理、認可の正規化、ページネーション、計画の機密情報のマスキング、ドライランのデフォルト、確認ガード、設定のオーバーライドを検証します。Yeelight のライブクラウドには接続しません。

ライセンス

Apache License 2.0。詳細は LICENSE と NOTICE を参照してください。