LIFX MCP Server

A TypeScript-based MCP server for controlling LIFX smart lights via the official LIFX HTTP API.

Features

• Control LIFX lights using MCP tools
• Set state, toggle, and apply effects (breathe, move, morph, flame)
• Activate scenes and parse color strings

Getting Started

Prerequisites

• Node.js (v16+ recommended)
• A LIFX Cloud API token (get one here)
• MCP-compatible client (e.g., VS Code)

Installation

git clone https://github.com/your-org/mcp-lifx.git
cd mcp-lifx
npm install

Build

npm run build

Run

You can start the server directly:

npm start

Or use MCP tooling (recommended):

npx fastmcp dev src/index.ts

Usage with VS Code

For quick installation, use one of the one-click install buttons at the top of this README.

For manual installation, add the following JSON block to your User Settings (JSON) file in VS Code. You can do this by pressing Ctrl + Shift + P and typing Preferences: Open User Settings (JSON).

Optionally, you can add it to a file called .vscode/mcp.json in your workspace. This will allow you to share the configuration with others.

Note that the mcp key is not needed in the .vscode/mcp.json file.

{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "lifx_token",
        "description": "LIFX Cloud API Token",
        "password": true
      }
    ],
    "servers": {
      "lifx": {
        "command": "npx",
        "args": ["-y", "mcp-lifx"],
        "env": {
          "LIFX_TOKEN": "${input:lifx_token}"
        }
      }
    }
  }
}

Configuration

The server requires a LIFX API token. You can provide it via:

• .env file:

  LIFX_TOKEN=your_lifx_token_here

• Or via the VS Code MCP extension prompt (see .vscode/mcp.json).

Usage

The server exposes the following MCP tools:

State Management

• get-lights: Get current state of lights by selector
• set-state: Set state (power, color, brightness, infrared)
• set-states: Set multiple states for different lights at once
• set-state-delta: Apply incremental changes to light states
• toggle-lights: Toggle power state
• cycle-lights: Cycle through a sequence of states

Effects

• breathe-effect: Gentle fade between colors
• move-effect: Create movement animation
• morph-effect: Transition through color palette
• pulse-effect: Sharp transitions between colors
• clouds-effect: Subtle color variations
• sunrise-effect: Simulate sunrise
• sunset-effect: Simulate sunset
• flame-effect: Fire-like animation
• clean-effect: Clean white light
• off-effect: Turn off with options
• stop-effect: Stop any running effect

Scene Management

• get-scenes: List all available scenes
• activate-scene: Activate a specific scene

Utilities

• parse-color: Parse color strings into LIFX color format

Usage Examples

Toggle a Light

{
  "tool": "toggle-lights",
  "parameters": {
    "selector": "label:Lamp"
  }
}

Set Light State

{
  "tool": "set-state",
  "parameters": {
    "selector": "label:Lamp",
    "state": {
      "power": "on",
      "brightness": 1.0,
      "color": "blue",
      "duration": 1.0
    }
  }
}

Run Breathe Effect

{
  "tool": "breathe-effect",
  "parameters": {
    "selector": "label:Lamp",
    "effect": {
      "color": "red",
      "period": 1.0,
      "cycles": 5,
      "persist": false,
      "power_on": true
    }
  }
}

Stop Effects

{
  "tool": "stop-effect",
  "parameters": {
    "selector": "label:Lamp"
  }
}

Selectors

Lights can be selected using various selector types:

• label:NAME - Select by light label
• id:DEVICE_ID - Select by device ID
• group:GROUP_NAME - Select by group name
• location:LOCATION_NAME - Select by location
• all - Select all lights

Color Formats

Colors can be specified in multiple formats:

• Named colors: "red", "blue", "green", etc.
• Hex: "#FF0000"
• RGB: "rgb:255,0,0"
• HSB: "hsb:360,100,100"
• Kelvin: "kelvin:3500"

Development

• TypeScript source: src/
• Build output: build/
• Types and schemas: src/types.ts

Scripts

• npm run build – Compile TypeScript to build/
• npm start – Run the compiled server
• npm run dev – Run with tsx for development

API Reference

See .docs/lifxapi.md for full LIFX API details and color formats.

License

ISC

This project is not affiliated with LIFX. Use at your own risk.