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.

---

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