Govee

govee-mcp

Govee スマートデバイス向けの、LAN 優先でクラウドにフォールバックするModel Context Protocol（MCP）サーバーです。AI エージェントや任意の MCP クライアントから、Govee のライト、プラグ、家電を指定し、名前で操作できます。

ホームネットワーク上で動作するように構築されています。ライトの操作にはローカル LAN 制御を優先します（高速で、インターネット不要、レート制限なし）。プラグ、家電、LAN 上で到達できないデバイスには、Govee のクラウド API を使用します。

ステータスと方針

これは、自分のネットワークで動作する v0 です。「ホームネットワーク上のエージェントで動くものを作ったので、使って、自分向けに改良し、必要に応じて堅牢にしてください」という考えで公開しています。サポート対象の製品ではありません。Issue やプルリクエストは歓迎しますが、完成品ではなく、出発点として扱ってください。

できること（v0）

• デバイスを検出し（クラウドアカウントのリストと LAN スキャン）、わかりやすい名前で指定します。
• 電源、明るさ、RGB カラー、白色の色温度を操作します。
• 現在のデバイス状態（電源、明るさ、色）を読み取ります。
• 動的シーン（プリセット効果）をデバイスごとに取得し、一覧表示して適用します（クラウドのみ）。
• デバイスをグループ化し、1 つのコマンド（オン／オフ、色、シーン、状態）をすべてのメンバーに適用します。
• LAN 対応ライトには LAN を優先し、それ以外はクラウドにフォールバックします。
• クライアント側のガードにより、Govee が公開しているクラウドの制限（1 分あたり 100 リクエスト、1 日あたり 10000 リクエスト）を超えないようにします。

まだできないこと（「堅牢にする」リスト）

• Bluetooth 温度・湿度センサー（H5075 など）。これらはクラウドや LAN API ではなく BLE 経由で読み取るため、次に取り組むものとして最も興味深い機能です。
• セグメントごとの色、ミュージックモード、DIY 効果。シーンには対応していますが、これらは残されたクラウド機能です。
• リアルタイムのプッシュ状態（Govee の AWS IoT チャネル）。

これらは、今後拡張できる余地として意図的に残しています。

比較

既存の Govee MCP サーバーは機能が限定的です。1 つはクラウド専用で、ハードコードされた 1 台のデバイスを 3 つのツールで操作し、もう 1 つは LAN 専用で、ライトのみを扱います。このサーバーは、複数デバイスの検出、両方の通信方式の自動選択、状態の読み戻し、クラウドのレート制限への対応を行います。

必要条件

• Python 3.10 以降。
• クラウド制御用の Govee API キー（任意ですが、プラグ、家電、LAN 非対応デバイスには必要です）。Govee Home アプリで取得できます。Profile、About Us の順に選択し、Apply for API Key を選びます。
• LAN 制御の場合：Govee Home アプリで各デバイスの「LAN Control」を有効にし、ネットワーク上で UDP ポート 4001、4002、4003 を通過できるようにしてください。

インストール

ソースからインストール：

git clone https://github.com/evefromwayback/govee-mcp.git
cd govee-mcp
pip install -e .

govee-mcp コマンドがインストールされます。インストールせずに実行するには：

PYTHONPATH=src python3 -m govee_mcp

設定

.env.example を .env にコピーして必要な項目を入力するか、MCP クライアントの設定で変数を設定してください。

変数	デフォルト	用途
GOVEE_API_KEY	(なし)	クラウド API キー。設定しない場合、サーバーは LAN 専用で動作します。
GOVEE_PREFER_LAN	true	デバイスに両方の方法で接続できる場合、クラウドより LAN を優先します。
GOVEE_LAN_ENABLED	true	LAN 通信を有効にします。
GOVEE_CLOUD_ENABLED	true	クラウド通信を有効にします（API キーも必要です）。
GOVEE_LAN_SCAN_IPS	(なし)	マルチキャストが不安定な場合に、直接スキャンするデバイス IP をカンマ区切りで指定します。
GOVEE_LAN_DISCOVERY_TIMEOUT	2	LAN 検出の応答を待つ秒数です。
GOVEE_REQUEST_TIMEOUT	10	クラウド HTTP のタイムアウト（秒）です。
GOVEE_DEVICE_CACHE_TTL	86400	デバイスリストを再検出するまでキャッシュする秒数です。より早く更新するには govee refresh を実行してください。
GOVEE_CACHE_ENABLED	true	ディスクにデバイスリストをキャッシュし、ほとんどのコマンドで検出を省略します。
GOVEE_CACHE_PATH	~/.cache/govee-mcp/devices.json	ディスク上のデバイスキャッシュの保存先です。

コマンドラインでの使用

小さな CLI がサーバーに付属しており、同じエンジンを使用するため、MCP クライアントに接続する前に動作を確認する最も手軽な方法です。まず doctor を実行してください。

govee doctor                   # check key, cloud, and LAN connectivity
govee devices                  # list devices (instant, from cache)
govee refresh                  # re-scan devices and show current state
govee state                    # full current state for every device
govee state "Desk Lamp"        # full current state for one device
govee on "Desk Lamp"
govee off "Desk Lamp"
govee brightness "Desk Lamp" 40
govee color "Desk Lamp" 255 0 0
govee temp "Desk Lamp" 4000
govee scenes "Desk Lamp"       # list this device's scenes
govee scene "Desk Lamp" "Sunrise"
govee groups                   # list device groups
govee group "Living Room" "Bulb 1" "Bulb 2"   # create or replace a group
govee ungroup "Living Room"    # delete a group

コマンドのリファレンスを表示するには、govee help を実行するか、引数なしで govee を実行してください。doctor は、キーが読み込まれたか、クラウドアカウントにデバイスが何台あるか、LAN 上で応答したデバイスが何台あるかを報告し、不足しているものについてヒントを表示します。govee が PATH 上にない場合は、代わりに python3 -m govee_mcp.cli ... を使用してください。

操作コマンドでは、デバイス名の代わりにグループ名も使用できます。govee group "Living Room" "Bulb 1" "Bulb 2" でグループを定義し、govee on "Living Room"、govee color "Living Room" 255 0 0、または govee state "Living Room" を実行すると、グループ内のすべてのデバイスに適用されます。グループは ~/.config/govee-mcp/groups.json に保存されます（GOVEE_GROUPS_PATH で変更できます）。

govee devices はキャッシュ内のデバイスを一覧表示するだけなので、すぐに実行できます。ライブ呼び出しは行いません。govee refresh はデバイスを再スキャンしてから、すべてのデバイスのライブ状態を表示します。govee state は、名前の指定の有無にかかわらず、常にライブ読み取りを行います。

MCP クライアントを接続する

Claude Desktop（claude_desktop_config.json）、インストール済みコマンド：

{
  "mcpServers": {
    "govee": {
      "command": "govee-mcp",
      "env": { "GOVEE_API_KEY": "your-key-here" }
    }
  }
}

ソースから実行する場合：

{
  "mcpServers": {
    "govee": {
      "command": "python3",
      "args": ["-m", "govee_mcp"],
      "env": {
        "GOVEE_API_KEY": "your-key-here",
        "PYTHONPATH": "/absolute/path/to/govee-mcp/src"
      }
    }
  }
}

Hermes Agent で使用する

Hermes Agent にはネイティブの MCP クライアントがあるため、このサーバーをそのまま追加できます。Hermes のカタログに登録したら、名前を指定してインストールします。

hermes mcp install govee

手動で接続するには、Hermes の設定の mcp_servers に追加し、Hermes の .env に GOVEE_API_KEY を設定してください（サーバープロセスはこの値を引き継ぎます）。

mcp_servers:
  govee:
    command: govee-mcp

govee-mcp が起動時の PATH 上にない場合は、絶対パスまたは python3 -m govee_mcp を使用してください。Hermes のカタログマニフェストは hermes/manifest.yaml に含まれています。

ツール

• list_devices(): 名前、対応する操作、トランスポートとともに、検出されたデバイスを一覧表示します。最初に呼び出してください。
• list_groups(): デバイスグループと、そのメンバーを一覧表示します。
• create_group(name, devices): グループを作成または置き換えます。
• delete_group(name): グループを削除します。
• get_device_state(name): 現在の電源状態、明るさ、色を取得します。
• refresh(): デバイスを再スキャンし、すべてのデバイスのライブ状態を返します。
• set_power(name, on): 電源をオンまたはオフにします。
• set_brightness(name, level): 0～100。
• set_color(name, red, green, blue): 各チャンネルは 0～255。
• set_color_temp(name, kelvin): およそ 2000（暖色）～9000（寒色）。
• list_scenes(name): デバイスが対応するダイナミックシーン（プリセット効果）を一覧表示します。
• set_scene(name, scene): 名前を指定してシーンを適用します。有効な名前を取得するには、先に list_scenes を呼び出してください。

各操作ツールの name には、単一のデバイス名またはグループ名（list_groups を参照）を指定できます。グループを指定すると、そのメンバーすべてに操作が適用されます。

シーン（Sunrise、Aurora などの「パターン」）はクラウド専用で、デバイスごとに異なるため、API キーが必要です。ハードコードされた値ではなく、各デバイスからライブで取得されます。その他の操作はどちらのトランスポートでも実行できます。各操作ツールは構造化された結果を返します。変更が実際に行われたとみなせるのは、ツールが ok=true を返した場合のみです。ツールの説明では、呼び出しが成功していない限り変更が行われたと主張しないようモデルに指示しています。

トランスポートの選択方法

各操作で、レジストリがトランスポートを選択します。

1. デバイスが LAN 上で検出された場合、対応する照明操作では LAN 制御が優先されます（ローカルで実行でき、従量課金もありません）。
2. それ以外の場合はクラウド API が使用されます。プラグ、家電製品、LAN 制御に対応していないデバイスでは、これが必要です。

常にクラウドを使用するには GOVEE_PREFER_LAN=false を設定してください。また、GOVEE_LAN_ENABLED=false または GOVEE_CLOUD_ENABLED=false でトランスポート全体を無効にできます。

API の利用条件とキーが必要な場合

Govee のクラウド Developer API は無料ですが、Govee によると非商用利用に限られます。営利目的で使用したり、この API を使った実装に対して料金を請求したりすることはできません。この制限はクラウドサービスに適用され、キーの提供者を問わず適用されます。このコードに対する制限ではありません。自宅で個人的に使用することも、このプロジェクトを無料で共有することも問題ありません。Govee と商用利用の条件を取り決めずに、無料のキーを使って有料製品を開発しないでください。Govee の API サービス利用規約をご覧ください：https://app-h5.govee.com/common/api-service-item

キーが常に必要なわけではありません。

• LAN モードではキーは不要で、Govee のサーバーに接続することもありません。照明のみを使用する場合は、それぞれの照明で LAN Control を有効にし、GOVEE_CLOUD_ENABLED=false を設定して実行してください。
• キーを使うと、Govee が LAN 経由で公開していないデバイス（プラグ、家電）にもサーバーから接続でき、照明に LAN 経由で接続できない場合のフォールバックとしても機能し、アカウントからわかりやすい名前や機能情報を取得できます。LAN 検出だけで取得できるのは、MAC アドレス、IP アドレス、モデル番号のみです。

セキュリティに関する注意事項と、ベンダリングとクローンについて

• このサーバーは、サードパーティ製デバイスライブラリを実行時依存関係として使用しません。Govee の LAN およびクラウドプロトコルは、Govee が公開しているプロトコルのドキュメントをもとに、ここで再実装しています。実行時依存関係は公式の MCP SDK（MIT）のみです。これにより、サプライチェーンのリスクを最小限に抑えられます。実行するのは、ご自身のコードと広く知られている SDK だけです。
• 後から既存の Govee ライブラリ（Bluetooth センサー向けなど）を追加する場合は、ライブで依存するよりも、特定のバージョンを固定して精査したコピーをベンダリングすることをおすすめします。ベンダリングすれば、実行されるコードを正確に確認でき、意図せず変更されることもなく、必要な部分だけに絞り込めます。その代わり、更新はご自身で管理する必要があります。コピーレフトのコードをベンダリングするとこのプロジェクトにもコピーレフトライセンスが適用されるため、許諾的なライセンスのコードのみをベンダリングしてください。
• API キーは環境変数から読み込まれ、ログに記録されることはありません。.env をコミットしないでください。
• LAN 制御では、Govee の LAN API の仕組みとして、ローカルネットワーク上の認証なし UDP を使用します。IoT デバイスは、信頼できるネットワークまたは分離されたネットワークに配置してください。
• テレメトリーはありません。サーバーが通信するのは、お使いのデバイスと、利用する場合は Govee の API のみです。

テスト

pip install -e ".[test]"
pytest

テストではクラウドの HTTP レイヤーをモックし、UDP 経由でローカルの偽 Govee デバイスを実行するため、API キーも実機も必要ありません。

ライセンスとクレジット

MIT です。LICENSE をご覧ください。

プロトコルは、Govee が公開している LAN ガイドと Developer API v2 のドキュメントをもとに実装しました。この分野を最初に切り開いたオープンソースプロジェクト（govee2mqtt、govee-led-wez、homebridge-govee、Govee BLE センサーの各プロジェクト）に感謝します。これらからコードをコピーしたわけではありません。参考資料としてクレジットを記載しています。

ロードマップ

• v1：Bluetooth センサーの読み取り（温度と湿度）、セグメントごとの色設定、音楽モード、オプションのリアルタイム状態。