Smart Bulb MCP Server
Smart Bulb MCP Server
一个基于 Node.js 和 TypeScript 构建的 Model Context Protocol (MCP) 服务器,用于通过 IP 控制智能灯泡。它支持:
Mock/模拟灯泡:无需物理硬件即可进行本地测试和开发。
Yeelight/Xiaomi 灯泡:使用标准 TCP 端口
55443(本地控制 JSON-RPC 协议)控制真实的物理智能灯泡。
功能特性
通过 IP 连接:动态连接本地网络中的不同灯泡。
电源控制:打开或关闭灯泡。
亮度与不透明度:将灯泡亮度/强度从 1% 调整到 100%。
颜色控制:使用 RGB 坐标或十六进制颜色值设置颜色。
状态查询:实时获取灯泡的当前状态。
Related MCP server: wiz-light-mcp
快速开始
1. 构建服务器
首先,安装依赖并编译 TypeScript 文件:
# Install dependencies
npm install
# Compile the TypeScript files
npm run build编译后的文件将输出到 dist/ 目录。
2. 运行 / 开发
您可以直接通过标准 I/O(Stdio)运行服务器:
# Run the built JS
npm start
# Compile and run in development mode
npm run dev配置 MCP 客户端
要将此服务器与 MCP 客户端(如 Claude Desktop 或 Cursor)配合使用,请将服务器配置添加到您的配置文件中。
适用于 Claude Desktop
编辑 claude_desktop_config.json(在 Windows 上通常位于 %APPDATA%\Claude,在 macOS 上通常位于 ~/Library/Application Support/Claude):
{
"mcpServers": {
"smart-bulb": {
"command": "node",
"args": ["D:/Palwinder/mcp-server-bulb/dist/index.js"]
}
}
}注意:请将 D:/Palwinder/mcp-server-bulb/dist/index.js 为您机器上 dist/index.js 的绝对路径。
对外提供的 MCP 工具
服务器连接后,宿主 LLM 将可以访问以下工具:
1. connect_bulb
连接到一个指定 IP 的灯泡。
参数:
ip(string,必填):IP 地址(例如"192.168.1.15"或"127.0.0.1")。type(枚举["mock", "yeelight"],默认值"mock"):驱动程序类型。使用"mock"可在没有物理硬件的情况下测试服务器功能,使用"yeelight"则用于控制真实的 Yeelight 灯泡。port(number,可选):要使用的端口。Yeelight 默认为55443,Mock 默认为9999。
2. disconnect_bulb
断开与当前连接的灯泡的断开连接。
参数:无。
3. get_bulb_state
获取连接状态、电源状态、亮度/不透明度和 RGB 颜色。
参数:无。
4. set_bulb_power
打开或关闭灯泡。
参数:
power(boolean,必填):true表示打开,false表示关闭。
5. set_bulb_brightness
设置灯泡的亮度/不透明度。
参数:
brightness(number,必填):取值为1到100。
6. set_bulb_color_rgb
使用 RGB 值设置灯泡颜色。
参数:
r(number,必填):红色分量0-255。g(number,必填):绿色分量0-255。b(number,必填):蓝色分量0-255。
7. set_bulb_color_hex
使用十六进制颜色代码实现设置灯泡颜色。
参数:
hex(string,必填):十六进制代码(例如"#FF0000"或"00FF00")。
OpenAI 集成客户端
我们在 src/openai-client.ts 中构建了一个客户端封装,使您可以直接将提示词发送给 OpenAI。OpenAI 随后会自动调用 MCP 工具来对您的智能灯泡执行操作。
客户端设置与运行
设置您的 OpenAI API 密钥: 在 Windows(PowerShell)上:
$env:OPENAI_API_KEY="your-actual-api-key"在 macOS/Linux(Bash)上:
export OPENAI_API_KEY="your-actual-api-key"运行客户端:
交互式 CLI 模式:
npm run client这会打开一个 shell 提示符。尝试输入:
连接到模拟灯泡,打开它,将其亮度设置为 80%,并将颜色设置为黄色。
一次性命令模式: 将您的提示直接作为参数传入:
npm run client -- "connect to the mock bulb, turn it on, and set color to blue"
自定义模型(可选): 默认情况下使用
gpt-4o-mini。您可以通过设置OPENAI_MODEL环境变量来更换:$env:OPENAI_MODEL="gpt-4o"
开发者详情与架构
该项目采用模块化架构:
src/bulb/interface.ts:定义通用契约(ISmartBulb)和状态结构(BulbState)。src/bulb/mock.ts:模拟灯泡实例,在内存中模拟网络延迟和状态变化。src/bulb/yeelight.ts:实现基于原始 TCP 行缓冲区的解析器,直接与物理 Yeelight WiFi 灯泡发送和接收 JSON-RPC 数据包,不依赖任何第三方 SDK。src/index.ts:挂载并配置@modelcontextprotocol/server工具,处理连接状态和校验模式。src/openai-client.ts:以子进程方式启动 MCP 服务器,动态加载其所有工具,将其暴露为 OpenAI Functions,并在多轮对话中执行工具调用循环。
由 Palwinder Singh 构建
Available Tools
7 toolsconnect_bulbA
Connect to a smart bulb at a given IP address. Supports both real Yeelight bulbs and mock bulbs for testing.
Inputs: ip (required), port, type.
disconnect_bulbA
Disconnect from the currently active smart bulb.
Inputs: no named parameters.
get_bulb_stateA
Retrieve the current state (power status, brightness/opacity, color) of the connected smart bulb.
Inputs: no named parameters.
set_bulb_brightnessA
Set the brightness (intensity/opacity) of the connected smart bulb.
Inputs: brightness (required).
set_bulb_color_hexA
Set the color of the connected smart bulb using a hexadecimal color code (e.g. '#FF0000' or '00FF00').
Inputs: hex (required).
set_bulb_color_rgbB
Set the color of the connected smart bulb using RGB values (0-255).
Inputs: b (required), g (required), r (required).
set_bulb_powerB
Turn the connected smart bulb on or off.
Inputs: power (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Tools have distinct purposes: connect, disconnect, state retrieval, and setting power, brightness, and color. The only overlap is between set_bulb_color_rgb and set_bulb_color_hex, which serve the same function with different input formats, but their descriptions clearly differentiate them, causing minimal confusion.
All tool names follow a consistent verb_noun pattern (e.g., connect_bulb, get_bulb_state, set_bulb_power). The naming style is uniform with snake_case and clear action-target structure, making the API predictable and easy to navigate.
With 7 tools, the set is well-scoped for a smart bulb control server. Each tool addresses a core operation (connection, state, power, brightness, color) without redundant or excessive entries, fitting comfortably within the ideal 3-15 range.
The server covers essential smart bulb operations: connection management, state retrieval, power, brightness, and color control. A minor gap is the lack of color temperature or scene settings, which are common on smart bulbs, but the core workflows are fully supported and no critical dead ends exist.
Related MCP Connectors
Yeelight device discovery, state, control, and scene execution.
Control and query Heiman smart home devices: lights, AC, curtains, climate, logs and scenes.
Control a Loxone Miniserver smart home: lights, blinds, climate, scenes and energy.
Yeelight home metadata and guarded management workflows.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables control of smart lights through MQTT messaging protocol, supporting operations like turning lights on/off and adjusting brightness levels from 0-100.-
- AlicenseAqualityDmaintenanceMCP server for controlling WiZ smart lights locally via UDP: discover bulbs, power control, color, temperature, and scenes.10MIT
- FlicenseNot gradedqualityDmaintenanceEnables control of Yeelight smart lights over local LAN, supporting on/off, brightness, color, temperature, and auto discovery.-
- AlicenseAqualityCmaintenanceEnables local network control of Tuya and Smart Life smart home devices without cloud round-trips, including power, brightness, color, and raw datapoint operations.9MIT