JinDaGe - govee_mcp_server MCP Details

article

README

🚀 Govee MCP 服务器

这是一个借助 Govee API 来控制 Govee LED 设备的 MCP 服务器，能为设备控制提供便捷的解决方案。

🚀 快速开始

本服务器可通过 Govee API 对 Govee LED 设备进行控制。在使用前，需完成环境变量的配置和服务器的安装。

✨ 主要特性

提供 MCP 服务器，可借助 Model Context Protocol 控制 Govee 设备，能与 Cline 或其他 MCP 客户端配合使用。
具备命令行界面（CLI），可直接对 Govee 设备进行控制。

📦 安装指南

通过 Smithery 安装

若要为 Claude 桌面版自动安装 Govee MCP 服务器，可访问 Smithery，并执行以下命令：

npx -y @smithery/cli install @mathd/govee_mcp_server --client claude

手动安装

# 通过 pip 安装
pip install .

# 开发用途（包含测试依赖）
pip install -e ".[test]"

💻 使用示例

基础用法

MCP 服务器

MCP 服务器提供了通过 Model Context Protocol 控制 Govee 设备的工具，以下是可用工具：

turn_on_off：打开或关闭 LED
set_color：使用 RGB 值设置 LED 颜色
set_brightness：设置 LED 亮度

命令行界面

提供了一个 CLI，用于直接控制 Govee 设备：

# 打开设备/关闭设备
govee-cli power on
govee-cli power off

# 使用 RGB 值设置颜色（0-255）
govee-cli color 255 0 0   # 红色
govee-cli color 0 255 0   # 绿色
govee-cli color 0 0 255   # 蓝色

# 设置亮度（0-100）
govee-cli brightness 50

运行 govee-cli --help 查看完整命令文档。

📚 详细文档

环境变量

需在根目录下创建一个 .env 文件，包含以下变量：

GOVEE_API_KEY=你的_api_key_这里
GOVEE_DEVICE_ID=你的设备_id_这里
GOVEE_SKU=你的设备_spu_这里

获取这些值的方法：

在 Govee 开发者控制台获取你的 API key
使用 Govee Home 应用来查找你的设备 ID 和 SKU

开发

运行测试

要运行测试套件：

# 安装测试依赖
pip install -e ".[test]"

# 运行所有测试
pytest tests/

# 运行特定的测试文件
pytest tests/test_server.py   # 服务器测试（模拟 API 调用）
pytest tests/test_cli.py      # CLI 测试（实际 API 调用）

# 以详细输出运行测试
pytest tests/ -v

⚠️ 重要提示

CLI 测试会进行实际的 API 调用，控制你的 Govee 设备。在运行这些测试之前，请确保设备已通电并连接。

项目结构

.
├── src/govee_mcp_server/
│   ├── __init__.py
│   ├── server.py    # MCP 服务器实现
│   └── cli.py       # 命令行接口
├── tests/
│   ├── test_server.py  # 服务器测试（带模拟 API）
│   └── test_cli.py     # CLI 测试（实际 API 调用）
└── pyproject.toml      # 项目配置

测试覆盖率

服务器测试覆盖：
- 环境初始化
- Govee API 客户端方法
- 服务器工具和实用程序
- 错误处理
CLI 测试通过执行实际的 API 调用进行实时集成测试，以控制你的 Govee 设备。

govee_mcp_server