Govee

govee-mcp

一款 LAN 优先、云端备用的 Govee 智能设备模型上下文协议（MCP）服务。让 AI Agent 或任何 MCP 客户端连接到你的 Govee 灯具、插座和家电，并按名称控制它们。

它专为在家庭网络中运行而构建。灯具优先通过本地 LAN 控制（速度快、无需联网、没有速率限制）；对于插座、家电以及任何无法通过 LAN 访问的设备，则回退到 Govee 云 API。

状态与初衷

这是一个 v0 版本，能在我自己的网络中正常工作。我分享它的初衷是：“这是一个能在我的家庭网络中与 Agent 配合使用的工具，拿去用吧，按你的需要改造，并根据情况加强安全性。”它不是受支持的产品。欢迎提交问题和拉取请求，但请将它视为一个起点，而不是一个完成的成品。

它能做什么（v0）

• 发现你的设备（云账户列表加 LAN 扫描），并通过易记名称寻址。
• 控制电源、亮度、RGB 颜色和白光色温。
• 读取设备当前状态（电源、亮度、颜色）。
• 列出并应用动态场景（预设效果），按设备实时获取（仅限云端）。
• 将设备分组，让一条命令（开/关、颜色、场景、状态）应用于组内所有设备。
• LAN 功能可用的灯具优先通过 LAN 控制，其他设备则回退到云端。
• 通过客户端保护机制，遵守 Govee 公布的云端限制（每分钟 100 次请求，每天 10000 次）。

它暂时还不能做什么（“加强安全性”清单）

• 蓝牙温湿度传感器（例如 H5075）。这些设备通过 BLE 读取，而非云端或 LAN API；这是最值得优先实现的功能。
• 分段颜色、音乐模式和 DIY 效果。当前支持场景；这些是云端剩余的功能。
• 实时推送状态（Govee 的 AWS IoT 通道）。

这些功能是刻意留待后续扩展的。

对比

现有的 Govee MCP 服务都比较简单：一个仅支持云端，只能控制一个硬编码设备，并提供三个工具；另一个仅支持 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	(none)	云 API 密钥。没有此密钥时，服务仅运行 LAN 控制。
GOVEE_PREFER_LAN	true	设备可通过两种方式访问时，优先使用 LAN 而非云端。
GOVEE_LAN_ENABLED	true	启用 LAN 传输。
GOVEE_CLOUD_ENABLED	true	启用云端传输（还需要 API 密钥）。
GOVEE_LAN_SCAN_IPS	(none)	以逗号分隔的设备 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 下，并将 GOVEE_API_KEY 放入 Hermes 的 .env 文件中（服务器进程会继承该变量）：

mcp_servers:
  govee:
    command: govee-mcp

如果启动 PATH 中没有 govee-mcp，请使用其绝对路径或 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）；对组执行操作会将操作应用于其所有成员。

场景（即“模式”：日出、极光等）仅支持云端，并且因设备而异，因此需要 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 说明，仅限非商业用途。你不得将其用于营利目的，也不得向任何人收取基于它构建的实现的费用。此限制适用于云服务，并约束密钥的提供方，而非此代码。个人在家使用以及免费分享此项目都没有问题。请勿在未与 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 和型号。

安全说明，以及采用 vendoring 而非克隆

• 此服务不会将任何第三方设备库作为运行时依赖。这里根据 Govee 的公开协议文档，重新实现了 Govee LAN 和云端协议。唯一的运行时依赖是官方 MCP SDK（MIT）。这使供应链攻击面极小：你运行的只有自己的代码和一个广为人知的 SDK。
• 如果之后要通过现有 Govee 库扩展此项目（例如支持蓝牙传感器），优先选择 vendoring 一份固定版本且经过检查的副本，而不是在运行时依赖它。Vendoring 意味着你可以准确了解运行的代码，代码不会在你不知情的情况下发生变化，而且你可以精简到所需内容。代价是你需要负责更新。只 vendoring 采用宽松许可证的代码，因为 vendoring copyleft 代码会导致此项目改用相应许可证。
• 你的 API 密钥从环境变量读取，绝不会被记录到日志中。请勿提交你的 .env。
• LAN 控制在本地网络上使用未经身份验证的 UDP，这是 Govee LAN API 的工作方式。请将 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：读取蓝牙传感器数据（温度和湿度）、设置分段颜色、音乐模式，以及可选的实时状态。