CheerlLights MCP服务器
](https://www.python.org/downloads/)  
现代模型上下文协议（MCP）服务器，提供对CheerLights API的全面访问。CheerLights是一个全球物联网项目，可同步全球数千个连接灯的颜色，创造实时共享体验。
🌈 特性
工具（动作）
- 当前颜色：从全球网络获取最新的CheerLights颜色
- 颜色历史：使用可配置计数（1-100）检索最近的颜色变化
- 颜色统计：分析颜色使用模式和随时间的流行程度
- 颜色搜索：在历史数据中查找特定颜色
- 十六进制颜色代码：获取CheerLights颜色的十六进制代码和RGB值
资源（上下文）
- 当前颜色资源：实时当前颜色作为可读资源
- 历史资源：用于上下文注入的格式化颜色历史
- 支持的颜色：带十六进制代码的有效CheerLights颜色的完整列表
提示（模板）
- 趋势分析：生成分析CheerLights颜色趋势的提示
- 颜色报告：创建有关特定颜色的详细报告
🚀 快速开始
使用紫外线（推荐）
# Clone the repository
git clone https://github.com/cheerlights/cheerlights-mcp.git
cd cheerlights-mcp
# Install with uv
uv sync
# Run the server
uv run cheerlights-mcp使用pip
# Clone and install
git clone https://github.com/cheerlights/cheerlights-mcp.git
cd cheerlights-mcp
pip install -e .
# Run the server
python -m cheerlights_mcp.server📦 安装
为了发展
# Install with development dependencies
uv sync --dev
# Install pre-commit hooks
uv run pre-commit install来自PyPI（发布时）
pip install cheerlights-mcp🔧 用法
使用克劳德桌面
添加到您的Claude Desktop配置中：
视窗: %APPDATA%\Claude\claude_desktop_config.json\ macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"cheerlights": {
"command": "uv",
"args": ["run", "cheerlights-mcp"],
"cwd": "/path/to/cheerlights-mcp"
}
}
}直接执行
# Standard I/O (default)
python -m cheerlights_mcp.server
# With specific transport
python -m cheerlights_mcp.server stdio
python -m cheerlights_mcp.server sse
python -m cheerlights_mcp.server streamable-http程序化使用
from cheerlights_mcp import create_server
# Create and run server
server = create_server("My CheerLights Server")
server.run()🛠️ api参考
工具
get_current_cheerlights_color()
结构化回报 ColorData 与：
color：当前颜色名称timestamp：设置时entry_id：唯一标识符created_at：解析的日期时间（可选）
get_cheerlights_history(count: int = 5)
退货 ColorHistory 最近有变化（1-100个条目）。
analyze_color_statistics(sample_size: int = 50)
退货 ColorStatistics 与：
- 颜色频率计数
- 最受欢迎/最不受欢迎的颜色
- 分析期信息
- 独特的颜色计数
search_colors(color: str, limit: int = 20)
退货 ColorSearchResult 与匹配的条目。
get_hex_color_code(color_name: str)
退货 HexColor 使用十六进制代码和RGB值。
资源
cheerlights://current-当前颜色状态cheerlights://history/{count}-最近的颜色历史cheerlights://colors/supported-所有支持的颜色
Claude的查询示例
- “CheerLights目前的颜色是什么，上次更改是什么时候？”
- “显示最近20次CheerLights颜色变化”
- “分析最近100次更改的颜色使用统计数据”
- “搜索最近所有颜色为‘蓝色’的时间”
- “CheerLights‘暖白色’的十六进制代码是什么？”
- “创建CheerLights颜色趋势报告”
🧪 测试
# Run all tests
uv run pytest
# Run with coverage
uv run pytest --cov=cheerlights_mcp
# Run specific test files
uv run pytest tests/test_tools.py -v🏗️ 建筑
cheerlights-mcp/
├── src/cheerlights_mcp/
│ ├── api/ # ThingSpeak API client
│ ├── models/ # Pydantic data models
│ ├── tools/ # MCP tool implementations
│ ├── utils/ # Utilities (color mapping, statistics)
│ └── server.py # Main FastMCP server
├── tests/ # Comprehensive test suite
└── examples/ # Usage examples关键组件
- ThingSpeakClient：CheerLights API的异步HTTP客户端
- Pydantic模型：类型安全数据验证和序列化
- 结构化输出：全力支持MCP结构化响应
- 全面的错误处理：良好的退化和伐木
- 统计引擎：颜色使用分析和趋势计算
🎨 支持的颜色
CheerLights支持以下标准颜色：
- 主要的，重要的：红色、绿色、蓝色
- 次要的：青色、品红色、黄色
- 扩展的：橙色、粉色、紫色、白色、暖白色、旧蕾丝
- 效用：黑色
每种颜色都包含十六进制代码和RGB值，用于精确表示。
📊 示例数据
当前颜色响应
{
"color": "red",
"timestamp": "2024-01-15 14:30:22 UTC",
"entry_id": "12345",
"created_at": "2024-01-15T14:30:22Z"
}统计响应
{
"color_counts": {"red": 15, "blue": 12, "green": 8},
"most_popular": "red",
"least_popular": "green",
"total_changes": 35,
"unique_colors": 3,
"analysis_period": "2 hours"
}开发设置
# Clone and setup
git clone https://github.com/cheerlights/cheerlights-mcp.git
cd cheerlights-mcp
uv sync --dev
# Install pre-commit hooks
uv run pre-commit install
# Run tests
uv run pytest -v📝 更新日志
版本2.0.0
- 完全重写 使用现代MCP Python SDK
- 结构化输出 支持所有工具
- 增强型API客户端 通过适当的错误处理
- 全面的测试套件 覆盖率>90%
- 类型安全性 始终使用Pydantic模型
- 新工具：统计、搜索、十六进制颜色代码
- 资源和提示 实现更丰富的整合
- 现代包装 使用uv和pyproject.toml
版本1.0.0
- FastMCP的初步实施
- 基本的当前颜色和历史工具
- 简单的ThingSpeak集成
📄 许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。
🔗 链接
- CheerlLights项目: cheerllights.com
- MCP文件: 模型上下文协议.io
- ThingSpeak API: thingspeak.com
- 原创教程: 创建MCP服务器
🎄 关于CheerLights
CheerLights是一个全球物联网项目，它将世界各地的彩色灯光同步，以创建同步的灯光显示。该项目由Hans Scharler创建，自2011年以来已连接了全球数千盏灯。当有人改变颜色时 CheerLights Discord服务器，所有参与的灯光几乎实时地变为该颜色。
此MCP服务器为AI助手提供了对CheerLights数据的丰富访问，从而能够分析这个独特的物联网数据集中的全球照明趋势、颜色流行度和时间模式。