Smart Bulb MCP Server
Provides tools for controlling Xiaomi-compatible smart bulbs (including Yeelight) over IP, with capabilities for turning power on/off, adjusting brightness, setting RGB or hex colors, and querying the current bulb state.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Smart Bulb MCP Server connect to the mock bulb, turn it on, and set the color to blue"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 buildThe 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 devConfiguring 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 to55443for Yeelight, and9999for 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):trueto turn ON,falseto turn OFF.
5. set_bulb_brightness
Sets the bulb's brightness / opacity.
Arguments:
brightness(number, required): Values from1to100.
6. set_bulb_color_rgb
Sets the color of the bulb using RGB values.
Arguments:
r(number, required): Red component0-255.g(number, required): Green component0-255.b(number, required): Blue component0-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
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"Run the Client:
Interactive CLI mode:
npm run clientThis 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"
Customizing the Model (Optional): By default, it uses
gpt-4o-mini. You can change it by setting theOPENAI_MODELenvironment 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/servertools, 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 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.
Maintenance
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