lifx-mcp-server

marekkacprzak/lifx-mcp-server

3.1

If you are the rightful owner of lifx-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

A comprehensive Model Context Protocol (MCP) server for controlling LIFX smart lights, built with TypeScript and Bun.

Tools
5
Resources
0
Prompts
0

LIFX MCP 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