MCP Govee

Govee MCP服务器

A. 模型上下文协议（MCP） 用于控制Govee智能灯的服务器。支持两者 标准 （适用于Claude Desktop等MCP客户）和 超文本传输协议 灵活集成的模式。

什么是MCP？

模型上下文协议（MCP）是一个开放标准，使AI助手能够安全地连接到外部工具和数据源。该服务器实现了MCP，允许像Claude这样的人工智能助手通过自然语言命令控制您的Govee智能灯。

例子： 只需告诉克劳德“打开卧室灯”或“将客厅设置为暖白色”，无需密码！

目录

• 什么是MCP？
• 特性
• 快速开始

- 先决条件 - 安装

• 配置
• 用法

- 模式1:stdio（适用于MCP客户端） - 模式2:HTTP服务器 -

• 可用的MCP工具
• MCP客户端配置
• 运作原理
• 发展
• 建筑
• 故障排除
• 贡献
• 资源
• 许可证

特性

• 🔌 双模式支持 -用于MCP客户端的stdio传输+用于自定义集成的HTTP API
• 💡 全设备控制 -打开/关闭灯光，调整亮度，设置RGB颜色
• 🔍 设备发现 -列出并查询可用的Govee设备
• 🔐 认证 -基于安全令牌的客户端身份验证
• ⚡ 速率限制 -具有可配置限制的按客户端请求限制
• 📦 智能缓存 -设备状态缓存可最大限度地减少API调用
• 🔄 命令合并 -批处理快速命令以防止API溢出
• 🔁 使用回退重试 -临时故障的自动重试
• ✅ 经过全面测试 -全面的测试覆盖率（385+次测试）

快速开始

先决条件

• Node.js>=20.0.0
• 政府API密钥(在这里买一个)
• 注册到您帐户的Govee智能设备

安装

选项1：来自npm（即将推出）

npm install -g govee-mcp-server

选项2：来源

# Clone the repository
git clone https://github.com/ayushgoel24/govee-mcp-server.git
cd govee-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

# (Optional) Install globally for easier CLI access
npm link

运行后 npm link，您可以使用 govee-mcp 从任何地方执行命令，您的Claude Desktop配置可以使用 "command": "govee-mcp" 而不需要完整的路径。

配置

环境变量

使用环境变量配置服务器。您可以在 .env 直接归档或传递它们：

# Copy the example environment file
cp .env.example .env

必需变量

注： 对于stdio模式，仅 GOVEE_API_KEY 是必需的。 MCP_CLIENT_TOKENS 仅用于HTTP模式身份验证。

可选环境变量

用法

服务器可以在两种模式下运行：

模式1:stdio（适用于MCP客户端）

使用此模式连接与MCP兼容的客户端，如Claude Desktop、Cline或其他AI助手。

# Run with environment variable
GOVEE_API_KEY=your-api-key node dist/stdio.js

# Or use the CLI command (after global install)
GOVEE_API_KEY=your-api-key govee-mcp

# Development mode
GOVEE_API_KEY=your-api-key tsx src/stdio.ts

MCP检验员测试：

npx @modelcontextprotocol/inspector -e GOVEE_API_KEY=your-api-key node dist/stdio.js

模式2:HTTP服务器

对于自定义集成、webhook或需要REST API时，请使用此模式。

# Development mode (with hot reload)
npm run dev

# Production mode
npm run build
npm start

HTTP服务器启动于 http://localhost:3000 （可通过以下方式配置 PORT 和 HOST 环境变量）。

模式3：Docker（HTTP服务器）

在Docker容器中运行HTTP服务器：

# Build the Docker image
npm run docker:build

# Run with docker-compose
docker-compose up -d

# Or run directly
docker run -d \
  -p 3000:3000 \
  -e GOVEE_API_KEY=your-api-key \
  -e MCP_CLIENT_TOKENS=your-token \
  govee-mcp-server

HTTP API终结点

健康检查

GET /healthz

退货 200 OK 当服务器健康时。

列出设备

GET /devices
Headers:
  x-mcp-auth: 

返回与您的帐户关联的所有Govee设备的列表。

MCP工具调用

POST /mcp/invoke
Headers:
  x-mcp-auth: 
  Content-Type: application/json

Body:
{
  "tool": "",
  "params": { ... }
}

可用的MCP工具

服务器通过MCP协议公开以下工具：

示例用法

使用MCP客户端（stdio模式）

只需询问您的AI助手：

• “列出我的Govee设备”
• “打开卧室的灯”
• “将客厅灯设置为蓝色”
• “将厨房灯光调暗至50%”

使用HTTP API

curl -X POST http://localhost:3000/mcp/invoke \
  -H "Content-Type: application/json" \
  -H "x-mcp-auth: your-token" \
  -d '{
    "tool": "turn_on",
    "params": {
      "deviceId": "AA:BB:CC:DD:EE:FF"
    }
  }'

MCP客户端配置

克劳德桌面（stdio模式-推荐）

快速设置： 1. 安装： npm install -g govee-mcp-server （或 npm link 来源） 1. 从获取您的Govee API密钥 developer.govee.com 1. 将下面的配置添加到 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%\Claude\claude_desktop_config.json （Windows） 1. 重新启动克劳德桌面

配置文件位置：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• 窗户： %APPDATA%\Claude\claude_desktop_config.json

选项1：全局安装（推荐）

在全球范围内安装后 npm install -g govee-mcp-server 或 npm link:

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

选项2:npx（发布到npm时）

{
  "mcpServers": {
    "govee": {
      "command": "npx",
      "args": ["-y", "govee-mcp-server"],
      "env": {
        "GOVEE_API_KEY": "your-govee-api-key"
      }
    }
  }
}

选项3：本地开发/源代码安装

首先，获取安装的绝对路径：

cd /path/to/govee-mcp-server
pwd  # Copy this path

然后在配置中使用完整路径：

{
  "mcpServers": {
    "govee": {
      "command": "node",
      "args": ["/Users/yourusername/projects/govee-mcp-server/dist/stdio.js"],
      "env": {
        "GOVEE_API_KEY": "your-govee-api-key"
      }
    }
  }
}

提示： 替换 /Users/yourusername/projects/govee-mcp-server 从实际路径 pwd 上面的命令。

验证您的设置

在配置Claude Desktop之前，请测试服务器是否正常工作：

# If installed globally or via npm link:
GOVEE_API_KEY=your-api-key govee-mcp

# If using local path:
GOVEE_API_KEY=your-api-key node /path/to/govee-mcp-server/dist/stdio.js

# Test with MCP Inspector:
npx @modelcontextprotocol/inspector -e GOVEE_API_KEY=your-api-key govee-mcp

如果服务器启动时没有错误，则可以配置Claude Desktop。更新配置后，重新启动Claude Desktop以使更改生效。

HTTP模式集成

对于使用HTTP API的自定义集成：

{
  "mcpServers": {
    "govee": {
      "url": "http://localhost:3000",
      "headers": {
        "x-mcp-auth": "your-client-token"
      }
    }
  }
}

注： HTTP模式要求单独启动服务器 npm start 以及配置 MCP_CLIENT_TOKENS 在您的环境中。

运作原理

graph LR
    A[MCP Client/Claude] -->|stdio| B[MCP Server]
    C[HTTP Client] -->|REST API| B
    B --> D[Device Service]
    D --> E[Govee API]
    E --> F[Smart Lights]
    D --> G[Cache Layer]
    D --> H[Rate Limiter]

1. MCP客户端/HTTP请求 → 您的AI助手或HTTP客户端发送工具调用
2. 认证 → 服务器验证凭据（stdio模式：无需，HTTP模式：基于令牌）
3. 速率限制 → 根据费率限制检查请求
4. 缓存检查 → 首先在缓存中检查设备状态
5. 政府API → 如果需要，服务器使用重试逻辑调用Govee API
6. 命令合并 → 批处理快速命令以防止API溢出
7. 响应 → 结果返回给客户端

发展

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch

# Lint code
npm run lint

# Fix lint issues
npm run lint:fix

建筑

src/
├── clients/        # External API clients (Govee)
├── config/         # Configuration management
├── middleware/     # Fastify middleware (auth, request ID, rate limiting)
├── routes/         # HTTP route handlers
├── schemas/        # Zod validation schemas
├── services/       # Business logic
├── types/          # TypeScript type definitions
└── utils/          # Utilities (cache, queue, retry, errors)

故障排除

stdio模式问题

MCP客户端未连接：

• 确保路径 dist/stdio.js 是绝对的
• 验证 GOVEE_API_KEY 在MCP客户端配置中设置
• 检查Node.js版本是否>=20.0.0
• 在MCP客户端的日志中查找错误消息

“找不到模块”错误：

• 跑 npm run build 将TypeScript编译为JavaScript
• 确保 dist/ 目录存在并包含已编译的文件

HTTP模式问题

“需要身份验证”错误：

• 确保你包括 x-mcp-auth 头球
• 验证令牌是否与您的 MCP_CLIENT_TOKENS 配置
• 检查一下 MCP_CLIENT_TOKENS 在您的环境中正确设置

“超出速率限制”错误：

• 您已超过配置的请求速率
• 等待速率限制窗口重置
• 增加 PER_CLIENT_RATE_LIMIT 如有需要

设备问题

未找到设备：

1. 验证设备ID是否正确（MAC地址格式： AA:BB:CC:DD:EE:FF)
2. 确保设备已注册到与您的API密钥关联的Govee帐户
3. 尝试通过重新启动服务器来刷新设备缓存
4. 直接在测试Govee API密钥 developer.govee.com

命令不起作用：

• 检查设备是否支持该命令（并非所有设备都支持所有功能）
• 确保设备联机并连接到WiFi
• 首先尝试通过官方Govee应用程序控制设备

政府API问题

429速率限制错误：

• Govee API有自己的速率限制（与此服务器的限制分开）
• 服务器将以指数回退方式自动重试
• 考虑增加 COALESCE_WINDOW_MS 批处理命令

无效的API密钥：

• 在验证您的API密钥 developer.govee.com
• 确保键中没有多余的空格或换行符
• 检查密钥是否已过期或被吊销

贡献

欢迎投稿！请随时提交拉取请求。对于重大更改，请先打开一个问题来讨论您想要更改的内容。

1. 分叉存储库
2. 创建功能分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'Add some amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

请确保：

• 所有测试均通过(npm test)
• 代码遵循linting规则(npm run lint)
• 您已为新功能添加了测试

资源

• 模型上下文协议文档
• 政府开发人员API
• MCP TypeScript SDK
• 克劳德桌面

支持

• 问题：
• 讨论：

许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

致谢

• 与 模型上下文协议SDK
• 由...驱动 政府开发人员API
• 用途 禁食 用于HTTP模式