Govee

io.github.evefromwayback由 GitHub 账号 evefromwayback 发布v0.2.0更新于 Oct 27, 2026

LAN-first, cloud-fallback MCP server for Govee smart lights and devices.

已验证STDIO仅桌面位置与生活效率与工作流

概览

AI 生成的概览

优先局域网、回退云端的 MCP 服务器,让助手按名称发现并控制 Govee 智能灯、插座和家电。

可以做什么
  • 发现设备与分组,并刷新全部设备的实时状态
  • 读取单个设备或分组的开关、亮度与颜色状态
  • 开关设备,设置亮度、RGB 颜色与白光色温
  • 列出并应用每台设备支持的动态场景(仅云端)
  • 创建、列出和删除设备分组,一条指令作用于组内所有成员
适用场景
当你希望 AI 助手在家庭网络中按友好名称控制 Govee 灯、插座或家电时使用;局域网可达的设备走本地控制,其余通过 Govee 云端 API。
运行要求
以本地 Python 包运行(需 Python 3.10 或更高版本,可通过 uvx 或 govee-mcp 命令启动)。云端控制、插座、家电和场景需要可选的 GOVEE_API_KEY;仅用局域网灯时无需密钥。局域网控制需在 Govee Home 应用中为每台设备开启 LAN Control,并允许网络通过 UDP 端口 4001、4002、4003。
安装前请注意
GOVEE_API_KEY 从环境变量读取,不应提交到代码库。局域网控制使用本地网络中未经认证的 UDP,建议将 IoT 设备放在可信或隔离的网络。控制工具会改变真实设备状态(开关、颜色、场景),分组会写入本地配置文件。Govee 免费云端 API 仅限非商业用途。该项目是未获官方支持的 v0 起点。

安装

在 SourceWeft 中

  1. 打开 控制台中的 Govee,将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only,通过 STDIO。 STDIO 服务会启动本地进程,因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

README

govee-mcp

A LAN-first, cloud-fallback Model Context Protocol (MCP) server for Govee smart devices. Point an AI agent, or any MCP client, at your Govee lights, plugs, and appliances and control them by name.

It is built to run on a home network. It prefers local LAN control for lights (fast, no internet, no rate limits) and falls back to Govee's cloud API for plugs, appliances, and anything not reachable on the LAN.

Status and spirit

This is a v0 that works for me on my own network. It is shared in the spirit of "here is something that works with an agent on my home network, have it, make it yours, and harden it as you please." It is not a supported product. Issues and pull requests are welcome, but treat it as a starting point rather than a finished appliance.

What it does (v0)

  • Discovers your devices (cloud account list plus a LAN scan) and addresses them by friendly name.
  • Controls power, brightness, RGB color, and white color temperature.
  • Reads current device state (power, brightness, color).
  • Lists and applies dynamic scenes (preset effects), fetched live per device (cloud-only).
  • Groups devices so one command (on/off, color, scene, state) applies to every member.
  • Prefers LAN for LAN-capable lights and falls back to the cloud for everything else.
  • Stays under Govee's published cloud limits (100 requests per minute, 10000 per day) with a client-side guard.

What it does not do yet (the "harden it" list)

  • Bluetooth temperature and humidity sensors (for example the H5075). Those are read over BLE, not the cloud or LAN API, and are the most interesting next step.
  • Per-segment color, music mode, and DIY effects. Scenes are supported; these are the remaining cloud capabilities.
  • Real-time push state (Govee's AWS IoT channel).

These are deliberately left as room to grow.

How it compares

The existing Govee MCP servers are thin: one is cloud-only and controls a single hardcoded device with three tools; another is LAN-only and lights-only. This one does multi-device discovery, both transports with automatic selection, state read-back, and cloud rate-limit handling.

Requirements

  • Python 3.10 or newer.
  • A Govee API key for cloud control (optional, but needed for plugs, appliances, and non-LAN devices). Get one in the Govee Home app: Profile, then About Us, then Apply for API Key.
  • For LAN control: enable "LAN Control" on each device in the Govee Home app, and make sure UDP ports 4001, 4002, and 4003 can pass on your network.

Install

From source:

git clone https://github.com/evefromwayback/govee-mcp.gitcd govee-mcppip install -e .

This installs a govee-mcp command. To run without installing:

PYTHONPATH=src python3 -m govee_mcp

Configure

Copy .env.example to .env and fill in what you need, or set the variables in your MCP client config.

VariableDefaultPurpose
GOVEE_API_KEY(none)Cloud API key. Without it, the server runs LAN-only.
GOVEE_PREFER_LANtruePrefer LAN over cloud when a device is reachable both ways.
GOVEE_LAN_ENABLEDtrueEnable the LAN transport.
GOVEE_CLOUD_ENABLEDtrueEnable the cloud transport (also needs an API key).
GOVEE_LAN_SCAN_IPS(none)Comma-separated device IPs to scan directly when multicast is flaky.
GOVEE_LAN_DISCOVERY_TIMEOUT2Seconds to wait for LAN discovery replies.
GOVEE_REQUEST_TIMEOUT10Cloud HTTP timeout in seconds.
GOVEE_DEVICE_CACHE_TTL86400Seconds to cache the device list before re-discovering. Run govee refresh to update sooner.
GOVEE_CACHE_ENABLEDtrueCache the device list on disk so most commands skip discovery.
GOVEE_CACHE_PATH~/.cache/govee-mcp/devices.jsonWhere the on-disk device cache is written.

Command-line use

A small CLI ships alongside the server and uses the same engine, so it is the fastest way to confirm things work before wiring up an MCP client. Start with doctor.

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

Run govee help, or just govee with no arguments, for the command reference. doctor reports whether your key loaded, how many devices are on your cloud account, and how many answered on the LAN, with a hint for whatever is missing. If govee is not on your PATH, use python3 -m govee_mcp.cli ... instead.

Any device name in the control commands can also be a group name. Define a group with govee group "Living Room" "Bulb 1" "Bulb 2", then govee on "Living Room", govee color "Living Room" 255 0 0, or govee state "Living Room" apply to every device in it. Groups are stored in ~/.config/govee-mcp/groups.json (override with GOVEE_GROUPS_PATH).

govee devices is instant: it lists devices from the cache and makes no live calls. govee refresh re-scans your devices and then prints the live state of all of them. govee state (with or without a name) is always a live read.

Connect an MCP client

Claude Desktop (claude_desktop_config.json), installed command:

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

Running from source instead:

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

Use with Hermes Agent

Hermes Agent has a native MCP client, so this server drops in. Once it is in the Hermes catalog, install it by name:

hermes mcp install govee

To wire it manually, add it under mcp_servers in your Hermes config and put GOVEE_API_KEY in your Hermes .env (the server process inherits it):

yaml
mcp_servers:  govee:    command: govee-mcp

If govee-mcp is not on the launch PATH, use its absolute path or python3 -m govee_mcp. A Hermes catalog manifest is included at hermes/manifest.yaml.

Tools

  • list_devices(): discovered devices with names, supported actions, and transports. Call this first.
  • list_groups(): device groups and their members.
  • create_group(name, devices): create or replace a group.
  • delete_group(name): delete a group.
  • get_device_state(name): current power, brightness, and color.
  • refresh(): re-scan devices and return the live state of all of them.
  • set_power(name, on): turn on or off.
  • set_brightness(name, level): 0 to 100.
  • set_color(name, red, green, blue): each channel 0 to 255.
  • set_color_temp(name, kelvin): roughly 2000 (warm) to 9000 (cool).
  • list_scenes(name): the dynamic scenes (preset effects) a device supports.
  • set_scene(name, scene): apply a scene by name. Call list_scenes first to get valid names.

Every control tool's name can be a single device or a group name (see list_groups); a group applies the action to all its members.

Scenes (the "patterns": Sunrise, Aurora, and so on) are cloud-only and differ per device, so they need an API key and are fetched live from each device rather than hardcoded. The other actions work over both transports. Each control tool returns a structured result. A change is only real when the tool returns ok=true; the tool descriptions instruct the model not to claim a change happened without a successful call.

How transport selection works

On each action the registry picks a transport:

  1. If the device was found on the LAN, LAN control is preferred (local and unmetered) for the light actions it supports.
  2. Otherwise the cloud API is used. This is required for plugs, appliances, and devices without LAN control.

Set GOVEE_PREFER_LAN=false to always use the cloud, or disable a transport entirely with GOVEE_LAN_ENABLED=false or GOVEE_CLOUD_ENABLED=false.

API terms and when you need a key

Govee's cloud Developer API is free but, per Govee, for non-commercial use only. You may not use it for profit-making purposes or charge anyone for an implementation built on it. That restriction is on the cloud service and applies to whoever supplies the key, not to this code. Personal home use and sharing this project for free are both fine. Do not build a paid product on the free key without arranging commercial terms with Govee. See Govee's API service terms: https://app-h5.govee.com/common/api-service-item

You do not always need a key:

  • LAN mode needs no key and never contacts Govee's servers. If you only have lights, enable LAN Control on each one and run with GOVEE_CLOUD_ENABLED=false.
  • The key is what lets the server reach devices Govee does not expose over the LAN (plugs, appliances), fall back when a light is not reachable on the LAN, and pull friendly names and capabilities from your account. LAN discovery alone only returns a MAC, an IP, and a model number.

Security notes, and on vendoring vs cloning

  • This server takes no third-party device library as a runtime dependency. The Govee LAN and cloud protocols are reimplemented here from Govee's public protocol documentation. The only runtime dependency is the official MCP SDK (MIT). That keeps the supply-chain surface tiny: you run your own code plus one well-known SDK.
  • If you extend this with an existing Govee library later (for example for Bluetooth sensors), prefer vendoring a pinned, inspected copy over depending on it live. Vendoring means you read exactly what runs, it cannot change under you, and you can trim it to what you need. The cost is that you own its updates. Only vendor permissively licensed code, since vendoring copyleft code would relicense this project.
  • Your API key is read from the environment and never logged. Do not commit your .env.
  • LAN control uses unauthenticated UDP on your local network, which is how Govee's LAN API works. Keep IoT devices on a trusted or segmented network.
  • No telemetry. The server talks only to your devices and, when used, Govee's API.

Testing

pip install -e ".[test]"pytest

The tests mock the cloud HTTP layer and run a local fake Govee device over UDP, so they need no API key and no real hardware.

License and attribution

MIT. See LICENSE.

The protocols were implemented from Govee's public LAN guide and Developer API v2 documentation. Thanks to the open-source projects that mapped this territory first (govee2mqtt and govee-led-wez, homebridge-govee, and the Govee BLE sensor projects). No code was copied from them; they are credited as references.

Roadmap

  • v1: Bluetooth sensor reads (temperature and humidity), per-segment color, music mode, and optional real-time state.

来源:README.md,提交 9847417

工具

0
SourceWeft 尚未在沙箱中启动过该软件包,因此其工具未知。

版本历史

1
  1. v0.2.0最新Sep 16, 2026

评分

已满足适用检查项的 50%

该评分衡量此收录条目的完整程度,依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价,也不表示服务器安全或当前可用:可连通性是带日期的检查结果,评分也不包含安装量或用户评价。

  • 近 30 天内可连通25 分

    请保持端点能够响应 MCP 握手;SourceWeft 每 30 天探测一次。

  • 已声明认证方式10 分

    请在注册中心条目中声明凭据请求头,或保持端点能够响应探测,以便判定其认证方式。

  • 已列出工具15 分

    请让服务器在无凭据时响应 tools/list,或发布可在沙箱中无凭据启动的软件包。

  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分