Govee MCP Server

🚀 Govee MCP Server

An MCP server that controls Govee LED devices via the Govee API.

🚀 Quick Start

Environment Variables

Create a .env file in the root directory with the following variables:

GOVEE_API_KEY=your_api_key_here
GOVEE_DEVICE_ID=your_device_id_here
GOVEE_SKU=your_device_spu_here

How to obtain these values:

1. Get your API key from the Govee developer console.
2. Use the Govee Home app to find your device ID and SKU.

✨ Features

• Control Govee LED devices through the Govee API.
• Provide MCP server and CLI tools for easy operation.

📦 Installation

Install via Smithery

To automatically install the Govee MCP server for Claude Desktop, visit Smithery:

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

Manual Installation

# Install via pip
pip install .

# For development purposes (including test dependencies)
pip install -e ".[test]"

💻 Usage Examples

MCP Server

The MCP server provides tools to control Govee devices through the Model Context Protocol. It can be used with Cline or other MCP clients. Available tools:

• turn_on_off: Turn the LED on or off.
• set_color: Set the LED color using RGB values.
• set_brightness: Set the LED brightness.

Command Line Interface

A CLI is provided to directly control Govee devices:

# Turn the device on/off
govee-cli power on
govee-cli power off

# Set the color using RGB values (0-255)
govee-cli color 255 0 0   # Red
govee-cli color 0 255 0   # Green
govee-cli color 0 0 255   # Blue

# Set the brightness (0-100)
govee-cli brightness 50

Run govee-cli --help to view the full command documentation.

🔧 Technical Details

Running Tests

To run the test suite:

# Install test dependencies
pip install -e ".[test]"

# Run all tests
pytest tests/

# Run a specific test file
pytest tests/test_server.py   # Server tests (simulating API calls)
pytest tests/test_cli.py      # CLI tests (actual API calls)

# Run tests with verbose output
pytest tests/ -v

⚠️ Important Note

CLI tests make actual API calls to control your Govee device. Make sure the device is powered on and connected before running these tests.

Project Structure

.
├── src/govee_mcp_server/
│   ├── __init__.py
│   ├── server.py    # MCP server implementation
│   └── cli.py       # Command-line interface
├── tests/
│   ├── test_server.py  # Server tests (with simulated API)
│   └── test_cli.py     # CLI tests (actual API calls)
└── pyproject.toml      # Project configuration

Test Coverage

• Server test coverage:
  • Environment initialization
  • Govee API client methods
  • Server tools and utilities
  • Error handling
• CLI tests perform real-time integration tests by making actual API calls to control your Govee device.