Yeelight MCP Server Natural Language Smart Lighting Control

Overview

Yeelight MCP Server is a lightweight bridge that lets developers control Yeelight smart lighting using natural language and structured tool calls. It implements a Model Context Protocol (MCP) interface so language models, chat agents, or other automation systems can request device discovery, read device state, and execute lighting actions (turn on/off, set color, set brightness, etc.) in a predictable, machine-friendly way.

The server translates between human-friendly prompts and concrete device operations, exposing RESTful endpoints and a tools/schema surface for LLM agents. This makes it easier to build conversational assistants, automation workflows, or agent-driven scenes that manage Yeelight devices without deep knowledge of the device APIs or network discovery mechanics.

Features

• Natural language → actionable device commands via MCP-compatible endpoints
• REST API for device discovery, state inspection, and action execution
• Tool/schema metadata for LLM agents (tool signatures, parameter schemas)
• Local and containerized deployment options
• Example payloads and sample integrations for quick prototyping
• Extensible mapping layer to add or override device actions and business rules

Installation / Configuration

Prerequisites (typical):

• Docker (optional)
• Node.js >= 16 or Python 3.9+ depending on chosen runtime (check repository)
• Network access to Yeelight devices (same LAN or cloud credentials)

Clone the repository:

git clone https://github.com/Yeelight/yeelight-iot-mcp.git
cd yeelight-iot-mcp

Run with Docker (recommended for isolation):

# build (if Dockerfile is present)
docker build -t yeelight-mcp .

# run with default port 8080 (example)
docker run -d -p 8080:8080 \
  -e MCP_PORT=8080 \
  -e YEELIGHT_DISCOVERY=true \
  -e AUTH_TOKEN="replace-with-secure-token" \
  yeelight-mcp

Run locally (example Node.js flow — adjust if repository uses a different runtime):

# install dependencies
npm install

# copy example env and edit credentials
cp .env.example .env
# edit .env to set YEELIGHT credentials, AUTH_TOKEN, and MCP_PORT

# start server
npm start

Example .env variables (table):

Note: Always protect AUTH_TOKEN and any cloud credentials. If exposing the server to remote LLMs, use HTTPS and an access control layer.

Available Resources

The server exposes a small set of HTTP endpoints (example routes; check the repo for exact paths):

• GET /health
  • Returns server health and version.
• GET /devices
  • Lists discovered/registered Yeelight devices with IDs and capabilities.
• POST /mcp
  • MCP entrypoint: accepts model prompts or structured tool calls and returns structured results/action proposals.
• POST /execute
  • Execute a validated device action (turn on/off, set brightness/color, etc.).
• GET /schema
  • Returns tool signatures and parameter schemas for LLMs and agent frameworks.

Example device object (typical response):

{
  "id": "device-123",
  "name": "Living Room Lamp",
  "type": "light",
  "capabilities": ["on_off", "brightness", "color"],
  "state": {
    "power": "on",
    "brightness": 80,
    "color": "#FFD580"
  }
}

Use Cases

1. Conversational assistant: “Dim the living room lights to 30% for movie time.”

   • Client: send natural language prompt to /mcp.
   • Server: returns an action proposal:

     {
       "tool": "set_brightness",
       "params": {
         "device_id": "device-123",
         "brightness": 30
       }
     }
     

   • Client: POST the proposal to /execute to apply it.

2. Scheduled scene creation:

   • User: “Every evening at 9pm, set the hallway light to warm white and 50%.”
   • Flow: /mcp suggests a structured schedule + actions; your scheduler stores the returned actions and calls /execute at the appointed times.

3. Multi-device orchestration:

   • Prompt: “Turn off all lamps in the kids’ room and set night-light on at 10%.”
   • Server discovers matching devices via GET /devices, synthesizes multiple tool calls, and returns an atomic execution plan to be applied sequentially.

4. Safety-aware automation:

   • The mapping layer can validate actions (e.g., prevent blinding brightness overnight), returning warnings or requiring explicit confirmation before /execute.

Examples (curl)

Discover devices:

curl -H "Authorization: Bearer $AUTH_TOKEN" http://localhost:8080/devices

Request an MCP action from natural language:

curl -X POST -H "Authorization: Bearer $AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Set living room lamp to cool blue at 60% brightness"}' \
  http://localhost:8080/mcp

Execute an action:

curl -X POST -H "Authorization: Bearer $AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tool":"set_color","params":{"device_id":"device-123","color":"#00AEEF","brightness":60}}' \
  http://localhost:8080/execute

Next Steps

• Inspect the repository for sample agent integrations and test scripts.
• Wire the server into an LLM agent framework (make sure to supply /schema/tool metadata to the model).
• Add custom validation or policies to the mapping layer for safer automations.

Repository and source: https://github.com/Yeelight/yeelight-iot-mcp