Lifx Server

A comprehensive Model Context Protocol (MCP) server for controlling LIFX smart lights, built with TypeScript and Bun. This server provides seamless integration between AI assistants and LIFX lighting systems.

Features

💡 LIFX Control Tools

• List Lights: Discover and list all LIFX lights with detailed information
• Set State: Control light power, color, brightness, and transitions
• Toggle Power: Smart power toggling based on current state
• Effects: Apply breathe, pulse, and other lighting effects
• Scenes: List and activate LIFX scenes
• Color Validation: Validate and convert color formats

📚 LIFX Resources

• Server Information: Runtime information and LIFX API status
• Color Examples: Comprehensive guide to LIFX color formats
• Selector Examples: Examples of LIFX light selector syntax

💬 Smart Prompts

• Lighting Scenes: Generate custom lighting setups for moods and activities
• Troubleshooting: Diagnose and fix LIFX lighting issues
• Color Recommendations: Get scientifically-backed color suggestions

🚀 Transport Support

• Stdio Transport: For Claude Desktop and command-line integration
• HTTP Transport: For web-based clients with session management

Installation

Prerequisites

• Bun installed on your system
• Node.js v18+ (for compatibility)
• LIFX API token from LIFX Cloud

Setup

# Clone or create the project
cd lifx-mcp-server

# Install dependencies
bun install

# Configure your LIFX API token
cp .env.example .env
# Edit .env and add your LIFX_API_TOKEN

Get Your LIFX API Token

1. Go to LIFX Cloud Settings
2. Generate a new personal access token
3. Copy the token to your .env file or pass it as a command line argument

Usage

Stdio Mode (for Claude Desktop, etc.)

# Start with token from environment
bun run start:stdio

# Or pass token directly
bun run src/index.ts --token=YOUR_LIFX_TOKEN

# Development mode with auto-reload
bun run dev

HTTP Mode (for web clients)

# Start HTTP server (requires token in .env)
bun run start:http

# The server will be available at:
# http://localhost:3000

Configuration for Claude Desktop

Add this to your Claude Desktop configuration:

{
  "mcpServers": {
    "lifx-mcp-server": {
      "command": "bun",
      "args": ["run", "src/index.ts", "--token=YOUR_LIFX_TOKEN"],
      "cwd": "/path/to/your/lifx-mcp-server"
    }
  }
}

LIFX Tools Reference

list-lights

Discover and list LIFX lights with detailed information.

Parameters:

• selector: string (default: "all") - Light selector (e.g., "all", "label:Kitchen", "group:Living Room")

Example:

{
  "name": "list-lights",
  "arguments": {
    "selector": "group:Living Room"
  }
}

set-state

Control light properties including power, color, brightness.

Parameters:

• selector: string (default: "all") - Light selector
• power: "on" | "off" (optional) - Power state
• color: string (optional) - Color (e.g., "red", "#ff0000", "kelvin:3500")
• brightness: number (optional) - Brightness (0.0 to 1.0)
• duration: number (optional) - Transition duration in seconds
• fast: boolean (optional) - Use fast mode for quicker response

Example:

{
  "name": "set-state",
  "arguments": {
    "selector": "label:Bedroom",
    "power": "on",
    "color": "blue saturation:0.5",
    "brightness": 0.7,
    "duration": 2
  }
}

toggle-power

Smart power toggle - turns off if any lights are on, turns on if all are off.

Parameters:

• selector: string (default: "all") - Light selector
• duration: number (optional) - Transition duration in seconds

breathe-effect

Apply a breathing effect to lights.

Parameters:

• selector: string (default: "all") - Light selector
• color: string - Effect color
• fromColor: string (optional) - Starting color
• period: number (default: 1.0) - Period in seconds
• cycles: number (default: 1.0) - Number of cycles
• persist: boolean (default: false) - Keep final color
• powerOn: boolean (default: true) - Turn on lights if off
• peak: number (default: 1.0) - Brightness peak (0.0 to 1.0)

pulse-effect

Apply a pulsing effect to lights.

Parameters:

• selector: string (default: "all") - Light selector
• color: string - Effect color
• fromColor: string (optional) - Starting color
• period: number (default: 1.0) - Period in seconds
• cycles: number (default: 1.0) - Number of cycles
• persist: boolean (default: false) - Keep final color
• powerOn: boolean (default: true) - Turn on lights if off

list-scenes

List all available LIFX scenes in your account.

activate-scene

Activate a LIFX scene by UUID.

Parameters:

• sceneUuid: string - Scene UUID
• duration: number (optional) - Transition duration
• ignore: string[] (optional) - Device IDs to ignore
• overrides: object (optional) - State overrides

validate-color

Validate a color string and get its HSBK representation.

Parameters:

• color: string - Color to validate

Color Format Guide

LIFX supports various color formats:

Named Colors

• Basic: "red", "blue", "green", "yellow", "orange", "purple", "pink", "cyan", "white"
• Extended: "gold", "coral", "lime", "navy", etc.

Hex Colors

• Standard: "#ff0000", "#00ff00", "#0000ff"
• Short: "#f00", "#0f0", "#00f"

HSL Format

• "hue:120 saturation:1.0"
• "hue:240 saturation:0.5 brightness:0.8"

Kelvin Temperature

• "kelvin:2700" (warm white)
• "kelvin:6500" (cool white)
• "kelvin:9000" (very cool)

Combined Formats

• "red brightness:0.3"
• "blue saturation:0.5"
• "kelvin:3500 brightness:0.8"

Light Selectors

LIFX uses powerful selectors to target specific lights:

Basic Selectors

• all - All lights
• id:d3b2f1d97452 - Specific light by ID

Label Selectors

• label:Kitchen - Single light by label
• label:Kitchen,Bedroom - Multiple lights by label

Group Selectors

• group:Living Room - All lights in a group
• group:Living Room,Kitchen - Multiple groups

Location Selectors

• location:Home - All lights at a location
• location:Home,Office - Multiple locations

Combined Selectors

• group:Living Room label:Lamp - Intersection
• location:Home group:Bedroom - Complex targeting

Example Usage Scenarios

1. Morning Routine

// Gradually turn on bedroom lights
{
  "name": "set-state",
  "arguments": {
    "selector": "group:Bedroom",
    "power": "on",
    "color": "kelvin:2700",
    "brightness": 0.3,
    "duration": 10
  }
}

2. Work Focus Setup

// Set office lights to cool white, high brightness
{
  "name": "set-state",
  "arguments": {
    "selector": "location:Office",
    "power": "on",
    "color": "kelvin:6500",
    "brightness": 0.9,
    "duration": 3
  }
}

3. Party Mode

// Apply colorful pulse effect
{
  "name": "pulse-effect",
  "arguments": {
    "selector": "all",
    "color": "hue:300 saturation:1.0",
    "period": 0.5,
    "cycles": 10,
    "persist": false
  }
}

4. Relaxation Scene

// Dim warm lights with breathing effect
{
  "name": "breathe-effect",
  "arguments": {
    "selector": "group:Living Room",
    "color": "kelvin:2200 brightness:0.2",
    "period": 4,
    "cycles": 5,
    "persist": true
  }
}

Development

Project Structure

src/
├── index.ts          # Main LIFX MCP server implementation
├── server-http.ts    # HTTP transport server
└── test-client.ts    # Test client for development

package.json         # Dependencies and scripts
tsconfig.json       # TypeScript configuration
.env                 # Environment configuration
README.md           # This file

Testing

# Run the test client
bun run test:manual

# Build for production
bun run build

# Format code
bun run format

# Lint code
bun run lint

Security & Best Practices

• Store your LIFX API token securely
• Use environment variables instead of hardcoding tokens
• Be mindful of rate limits when making frequent API calls
• Test selectors to ensure they target the correct lights
• Use fast=true mode sparingly for better reliability

Troubleshooting

Common Issues

1. API Token Invalid: Check your token at LIFX Cloud Settings
2. No Lights Found: Verify lights are online and connected to WiFi
3. Selector Not Working: Check light labels and group names in LIFX app
4. Rate Limit Errors: Reduce frequency of API calls
5. Effects Not Working: Ensure lights support the requested effect type

Debug Mode

Set DEBUG=true in your .env file for detailed API request/response logging.

License

MIT License - see LICENSE file for details.

Resources

• LIFX HTTP API Documentation
• LIFX Cloud Settings
• Model Context Protocol Specification
• MCP TypeScript SDK