Skip to main content
Glama

Smart Bulb MCP Server

A Model Context Protocol (MCP) server built with Node.js and TypeScript to control smart bulbs over IP. It supports:

  • Mock/Simulated Bulb: For local testing and development without physical hardware.

  • Yeelight/Xiaomi Bulb: Uses standard TCP port 55443 (local control JSON-RPC protocol) to control real physical smart bulbs.

Features

  • Connect using IP: Dynamically connect to different bulbs on your local network.

  • Power Control: Turn the bulb on or off.

  • Brightness & Opacity: Adjust bulb brightness / intensity from 1% to 100%.

  • Color Control: Set colors using RGB coordinates or hexadecimal color codes.

  • State Queries: Fetch the current state of the bulb in real-time.


Related MCP server: wiz-light-mcp

Getting Started

1. Build the Server

First, install the dependencies and compile the TypeScript files:

# Install dependencies
npm install

# Compile the TypeScript files
npm run build

The compiled files will be output to the dist/ directory.

2. Run / Development

You can run the server directly via standard I/O (Stdio):

# Run the built JS
npm start

# Compile and run in development mode
npm run dev

Configuring with MCP Clients

To use this server with an MCP client (such as Claude Desktop or Cursor), add the server configuration to your configuration file.

For Claude Desktop

Edit your claude_desktop_config.json (typically located in %APPDATA%\Claude on Windows or ~/Library/Application Support/Claude on macOS):

{
  "mcpServers": {
    "smart-bulb": {
      "command": "node",
      "args": ["D:/Palwinder/mcp-server-bulb/dist/index.js"]
    }
  }
}

Note: Replace D:/Palwinder/mcp-server-bulb/dist/index.js with the absolute path to dist/index.js on your machine.


Exposed MCP Tools

Once the server is connected, the host LLM will have access to the following tools:

1. connect_bulb

Connects to a bulb at a specified IP.

  • Arguments:

    • ip (string, required): IP address (e.g. "192.168.1.15" or "127.0.0.1").

    • type (enum ["mock", "yeelight"], default: "mock"): Driver type. Use "mock" to test the server features without physical hardware, or "yeelight" for real Yeelight bulbs.

    • port (number, optional): Port to use. Defaults to 55443 for Yeelight, and 9999 for Mock.

2. disconnect_bulb

Disconnects from the currently connected bulb.

  • Arguments: None.

3. get_bulb_state

Retrieves the connection status, power state, brightness/opacity percentage, and RGB color.

  • Arguments: None.

4. set_bulb_power

Turns the light bulb ON or OFF.

  • Arguments:

    • power (boolean, required): true to turn ON, false to turn OFF.

5. set_bulb_brightness

Sets the bulb's brightness / opacity.

  • Arguments:

    • brightness (number, required): Values from 1 to 100.

6. set_bulb_color_rgb

Sets the color of the bulb using RGB values.

  • Arguments:

    • r (number, required): Red component 0 - 255.

    • g (number, required): Green component 0 - 255.

    • b (number, required): Blue component 0 - 255.

7. set_bulb_color_hex

Sets the color of the bulb using a hex color code.

  • Arguments:

    • hex (string, required): Hex code (e.g., "#FF0000" or "00FF00").


OpenAI Connection Client

We have built a client wrapper in src/openai-client.ts that allows you to feed prompts directly to OpenAI. OpenAI will then autonomously invoke the MCP tools to perform the actions on your smart bulb.

Setup and Running the Client

  1. Set your OpenAI API Key: On Windows (PowerShell):

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

    On macOS/Linux (Bash):

    export OPENAI_API_KEY="your-actual-api-key"
  2. Run the Client:

    • Interactive CLI mode:

      npm run client

      This opens a shell prompt. Try typing:

      Connect to the mock bulb, turn it on, set its brightness to 80% and color to yellow.

    • One-off command mode: Pass your prompt directly as arguments:

      npm run client -- "connect to the mock bulb, turn it on, and set color to blue"
  3. Customizing the Model (Optional): By default, it uses gpt-4o-mini. You can change it by setting the OPENAI_MODEL environment variable:

    $env:OPENAI_MODEL="gpt-4o"

Developer Details & Architecture

The project has a modular architecture:

  • src/bulb/interface.ts: Defines the common contract (ISmartBulb) and state shape (BulbState).

  • src/bulb/mock.ts: Simulated bulb instance that mimics network latency and state changes in memory.

  • src/bulb/yeelight.ts: Implements a raw TCP line-based buffer parser to send and receive JSON-RPC packets directly from physical Yeelight WiFi bulbs without any third-party SDK dependencies.

  • src/index.ts: Configures and mounts the @modelcontextprotocol/server tools, handling connection states and validation schemas.

  • src/openai-client.ts: Launches the MCP server as a subprocess, loads all its tools dynamically, exposes them as OpenAI Functions, and handles the multi-turn conversational tool execution loop.


Built by 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.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    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