Skip to main content
Glama

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 工具来对您的智能灯泡执行操作。

客户端设置与运行

  1. 设置您的 OpenAI API 密钥: 在 Windows(PowerShell)上:

    $env:OPENAI_API_KEY="your-actual-api-key"

    在 macOS/Linux(Bash)上:

    export OPENAI_API_KEY="your-actual-api-key"
  2. 运行客户端:

    • 交互式 CLI 模式:

      npm run client

      这会打开一个 shell 提示符。尝试输入:

      连接到模拟灯泡,打开它,将其亮度设置为 80%,并将颜色设置为黄色。

    • 一次性命令模式: 将您的提示直接作为参数传入:

      npm run client -- "connect to the mock bulb, turn it on, and set color to blue"
  3. 自定义模型(可选): 默认情况下使用 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 tools
connect_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

    A3.7/5.0

    Scored across 7 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      MCP server for controlling WiZ smart lights locally via UDP: discover bulbs, power control, color, temperature, and scenes.
      10
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables local network control of Tuya and Smart Life smart home devices without cloud round-trips, including power, brightness, color, and raw datapoint operations.
      9
      MIT