lifx-api-mcp-server

lifx-api-mcp-server

1
os_automationdeveloper_tools

The LIFX API MCP Server is an MCP server that enables users to control LIFX smart lights through natural language commands. It provides a variety of tools and features for managing light states, scenes, and effects using the LIFX API. The server can be configured and run locally, supporting multiple installation methods, including NPX and Docker.

LIFX API MCP Server

Docker Hub Version NPM Version Buy Me a Coffee

LIFX API MCP Server is a local Model Context Protocol (MCP) server providing access to LIFX devices using natural language via LLMs to perform actions like listing lights, setting states, activating scenes, and triggering effects through the LIFX HTTP API. Includes contextual resources and helpful prompts.

Contents

Quick Start

  1. Get a LIFX API Token:
  2. Install LIFX MCP Server: (Choose one method)
    • NPX (Recommended): 
      npx -y lifx-api-mcp-server@latest
    • Docker: 
      docker run --rm -i --network=host --pull=always furey/lifx-api-mcp-server
  3. Configure API Token:
    • Crucial Step: Set your token via one of these methods (priority order):
      1. Config File (Recommended): Edit ~/.lifx-api-mcp-server.jsonc (generate with npx -y lifx-api-mcp-server@latest config:create) and add your token to the apiToken field.
      2. Environment Variable: Set CONFIG_API_TOKEN=YOUR_LIFX_API_TOKEN.
      3. Command Line Argument (Least Recommended): Pass the token when running the server (e.g., npx ... YOUR_TOKEN).
  4. Set up MCP Client:
  5. Control Your Lights:
    • Start interacting with your LIFX devices using natural language (see Tutorial). Use resources like @lix-api:lifx://lights and prompts like @lix-api:effect-creator.

Features

Tools

  • list-lights: Gets lights belonging to the account, filterable by selector.
  • set-state: Sets the state (power, color, brightness, etc.) of selected lights.
  • set-states: Sets multiple states across multiple selectors in one request.
  • state-delta: Changes state properties (brightness, hue, saturation, kelvin, infrared) by a relative amount.
  • toggle-power: Toggles the power state of selected lights.
  • breathe-effect: Performs a breathe (fade) effect.
  • pulse-effect: Performs a pulse (flash) effect.
  • move-effect: Performs a move effect on linear devices (LIFX Z strips).
  • morph-effect: Performs a morph effect on Tile devices.
  • flame-effect: Performs a flame effect on Tile devices.
  • clouds-effect: Performs a clouds effect on Tile devices (FW >= 4.8).
  • sunrise-effect: Performs a sunrise effect on Tile devices (FW >= 4.8).
  • sunset-effect: Performs a sunset effect on Tile devices (FW >= 4.8).
  • effects-off: Turns off any running effects.
  • list-scenes: Lists available scenes in the account.
  • activate-scene: Activates a specified scene by its UUID.
  • cycle: Cycles selected lights through a list of predefined states.
  • validate-color: Validates a color string and returns its components.
  • clean: Controls LIFX Clean devices.

Resources

  • lifx://lights: Provides a summary list of available lights (ID, Label, Power, Connected). Fetches live data.
  • lifx://light/{selector}/state: Provides the detailed current state for the light(s) matching the selector. Supports autocompletion for selectors. Fetches live data.
  • lifx://scenes: Provides a list of available scenes (Name, UUID). Fetches live data.

Prompts

  • effect-creator: Guides the user through creating effect parameters and generates the corresponding tool command.
  • troubleshooter: Helps diagnose basic connectivity issues for specific lights by checking their status (fetches live data).
  • selector-helper: Lists available identifiers (labels, groups, locations, IDs) from live data to help users construct accurate selectors.

Other Features

  • Config File: Customize settings via ~/.lifx-api-mcp-server.jsonc.
  • Environment Variables: Override config settings (e.g., CONFIG_API_TOKEN, CONFIG_LOG_LEVEL).
  • Component Disabling: Selectively disable tools, resources, or prompts via config.
  • Direct API Mapping: Tools generally correspond 1:1 with LIFX API endpoints.
  • Error Handling: Provides feedback based on LIFX API responses and HTTP status codes.
  • Selector Support: Uses LIFX selectors (all, id:, label:, etc.) for targeting lights.
  • Color Support: Accepts standard LIFX color strings.
  • Docker Support: Run easily within a Docker container.

Installation

LIFX MCP Server can be installed and run in several ways:

Installation: NPX

[!NOTE]
NPX requires Node.js (v18+) installed.

# Ensure Node.js v18+ is installed
node --version

# Run the server (token should ideally be set via config/env)
npx -y lifx-api-mcp-server@latest [YOUR_LIFX_API_TOKEN_IF_NEEDED]

Installation: Docker Hub

[!NOTE]
Requires Docker installed.

# Ensure Docker is installed
docker --version

# Run the server (token should ideally be set via config/env)
# Mount config file (recommended):
docker run --rm -i --network=host \
  -v ~/.lifx-api-mcp-server.jsonc:/root/.lifx-api-mcp-server.jsonc:ro \
  --pull=always furey/lifx-api-mcp-server

# OR pass token via environment variable:
docker run --rm -i --network=host \
  -e CONFIG_API_TOKEN=YOUR_LIFX_API_TOKEN \
  --pull=always furey/lifx-api-mcp-server

# OR pass token as argument (least recommended):
docker run --rm -i --network=host \
  --pull=always furey/lifx-api-mcp-server YOUR_LIFX_API_TOKEN

(Replace furey/lifx-api-mcp-server with the actual Docker Hub image name if different)

Installation: Node.js from Source

[!NOTE]
Requires Node.js (v18+) and npm/yarn installed.

  1. Clone the repository (replace with actual URL if published): 
    git clone https://github.com/furey/lifx-api-mcp-server.git # Placeholder
cd lifx-api-mcp-server
  2. Install dependencies: 
    npm install
  3. Run the server (token should ideally be set via config/env): 
    node lifx-api-mcp-server.js [YOUR_LIFX_API_TOKEN_IF_NEEDED]

Installation: Docker from Source

[!NOTE]
Requires Docker installed.

  1. Clone the repository: 
    git clone https://github.com/furey/lifx-api-mcp-server.git # Placeholder
cd lifx-api-mcp-server
  2. Build the Docker image: 
    docker build -t lifx-mcp-server .
  3. Run the container (token should ideally be set via config/env): 
    # Using mounted config file (recommended):
docker run --rm -i --network=host \
  -v ~/.lifx-api-mcp-server.jsonc:/root/.lifx-api-mcp-server.jsonc:ro \
  lifx-mcp-server

# Using environment variable:
docker run --rm -i --network=host \
  -e CONFIG_API_TOKEN=YOUR_LIFX_API_TOKEN \
  lifx-mcp-server

# Using argument (least recommended):
docker run --rm -i --network=host \
  lifx-mcp-server YOUR_LIFX_API_TOKEN

Installation Verification

When the server starts successfully, you should see output like:

[LIFX MCP] LIFX API MCP Server vX.Y.Z starting…
[LIFX MCP] Loading config file: /path/to/.lifx-api-mcp-server.jsonc (or 'No config file found')
[LIFX MCP] Initializing MCP server…
[LIFX MCP] Registering MCP resources…
[LIFX MCP] Total MCP resources registered: X
[LIFX MCP] Registering MCP prompts…
[LIFX MCP] Total MCP prompts registered: Y
[LIFX MCP] Registering MCP tools…
[LIFX MCP] Total MCP tools registered: Z
[LIFX MCP] Creating stdio transport…
[LIFX MCP] Connecting MCP server transport…
[LIFX MCP] LIFX API MCP Server running.

Configuration

Customize the server's behavior via a config file or environment variables. The API token is the most critical setting.

Configuration: API Token (Priority Order)

  1. Config File (apiToken key): Create/edit ~/.lifx-api-mcp-server.jsonc. (Recommended)
  2. Environment Variable (CONFIG_API_TOKEN): Set CONFIG_API_TOKEN=YOUR_TOKEN.
  3. Command Line Argument: Pass token as the first argument when running the script. (Least Recommended)

Configuration: Config File

Create a configuration file at ~/.lifx-api-mcp-server.jsonc (or .json). Use npx -y lifx-api-mcp-server@latest config:create to generate it.

Example configuration file (`~/.lifx-api-mcp-server.jsonc`) 
{
  // Your LIFX Personal Access Token (Required if not using ENV or CLI arg)
  // Get from: https://cloud.lifx.com/settings
  "apiToken": "YOUR_LIFX_API_TOKEN_HERE",

  // Log level: "info" (default) or "verbose" for more detailed logs including rate limits
  "logLevel": "info",

  // --- Optional: Disable specific components ---
  // Add component names here to disable them. Examples:
  // "disabled": {
  //   "tools": ["clean", "cycle"], // Disable specific tools
  //   "resources": ["scenes"],     // Disable the scenes resource
  //   "prompts": true              // Disable all prompts
  // },
  "disabled": {
    "tools": [],
    "resources": [],
    "prompts": []
  },

  // --- Optional: Enable only specific components ---
  // If an 'enabled' array is defined, ONLY those components of that type will be enabled,
  // overriding any 'disabled' settings for that type. Examples:
  // "enabled": {
  //    "tools": ["list-lights", "set-state"], // Only enable these two tools
  //    "resources": ["lights"]                // Only enable the lights resource
  // }
  "enabled": {
    "tools": null,
    "resources": null,
    "prompts": null
  }
}

Configuration: Config File Generation

You can generate a default configuration file automatically:

# NPX Usage (recommended)
npx -y lifx-api-mcp-server@latest config:create

# Node.js Usage (from source directory)
npm run config:create

# Force overwrite existing file
npx -y lifx-api-mcp-server@latest config:create -- --force
npm run config:create -- --force

# Specify custom path/filename (uses CONFIG_PATH env var)
CONFIG_PATH=/path/to/my-lifx-config.jsonc npm run config:create

This saves the example config content to ~/.lifx-api-mcp-server.jsonc by default.

Configuration: Environment Variable Overrides

Settings can be overridden using environment variables (take precedence over config file).

Config SettingEnvironment Variable OverrideExample Value
apiTokenCONFIG_API_TOKENc0ffee...
logLevelCONFIG_LOG_LEVELverbose
disabled.toolsCONFIG_DISABLED_TOOLSclean,cycle / true
enabled.toolsCONFIG_ENABLED_TOOLSlist-lights,set-state
disabled.resourcesCONFIG_DISABLED_RESOURCESscenes / true
enabled.resourcesCONFIG_ENABLED_RESOURCESlights,light-state
disabled.promptsCONFIG_DISABLED_PROMPTStroubleshooter / true
enabled.promptsCONFIG_ENABLED_PROMPTSeffect-creator

Example Usage:

# Set token and log level via environment variables when using NPX
CONFIG_API_TOKEN=YOUR_TOKEN CONFIG_LOG_LEVEL=verbose npx -y lifx-api-mcp-server@latest

# Same example using Docker
docker run --rm -i --network=host \
  -e CONFIG_API_TOKEN=YOUR_TOKEN \
  -e CONFIG_LOG_LEVEL=verbose \
  --pull=always furey/lifx-api-mcp-server

Client Setup

Configure your MCP client (e.g., Claude Desktop, MCP Inspector) to launch the lifx-api-mcp-server. Important: If you've configured the API token via the config file or environment variable, do not pass it as an argument in the client setup.

Client Setup: Claude Desktop

  1. Install Claude Desktop.

  2. Locate or create claude_desktop_config.json:

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json

  3. Add the server configuration (adjust paths as needed):

    {
  "mcpServers": {
    "lix-api": {
      // Use the full path to npx if it's not in your default PATH
      "command": "/path/to/your/npx", // Or node
      "args": [
        // NPX example: (NO TOKEN HERE if set in config/env)
        "-y",
        "lifx-api-mcp-server@latest"

        // Node.js from source example: (NO TOKEN HERE if set in config/env)
        // "/path/to/lifx-api-mcp-server/lifx-api-mcp-server.js"
      ],
      "env": {
         // Optional: Uncomment for verbose logging
         // "CONFIG_LOG_LEVEL": "verbose"
         // Optional: Set token via env if not using config file
         // "CONFIG_API_TOKEN": "YOUR_LIFX_API_TOKEN"
      }
    }
  }
}

  4. Restart Claude Desktop.

  5. Start a chat and try interacting with your lights (e.g., "@lix-api list my lights").

Client Setup: MCP Inspector

MCP Inspector is useful for debugging.

# Run MCP Inspector with the LIFX server (NO TOKEN HERE if set in config/env)
npx -y @modelcontextprotocol/inspector npx -y lifx-api-mcp-server@latest

# Open the inspector in your browser (usually http://localhost:5173)

Data Protection

  • API Token Security: Your LIFX API token grants control over your lights. Keep it confidential. Using the config file (~/.lifx-api-mcp-server.jsonc with appropriate file permissions) or environment variables is safer than passing the token as a command-line argument, especially in shared environments or logs.
  • Data Flow: When using a remote LLM (like via Claude Desktop), your prompts to the LLM and the results returned by this MCP server (light names, states, scene names) will be sent to the LLM provider. Be mindful of potentially sensitive information in your light/group/location/scene labels if privacy is a major concern.
  • Local Execution: This server runs locally on your machine. It communicates directly with the LIFX cloud API over HTTPS.

Tutorial

Ensure the server is running and connected to your MCP client. Replace placeholders like label:MyLamp with your actual light/group/location labels or IDs.

  1. Check Available Lights (Resource):

    • @lix-api:lifx://lights
    • ➥ Uses lights resource

  2. Get Specific Light State (Resource):

    • @lix-api:lifx://light/label:Office Lamp/state
    • ➥ Uses light-state resource

  3. Get Available Scenes (Resource):

    • @lix-api:lifx://scenes
    • ➥ Uses scenes resource

  4. Use Selector Helper (Prompt):

    • @lix-api:selector-helper goal: "the lights in the kitchen"
    • ➥ Uses selector-helper prompt

  5. Create an Effect (Prompt):

    • @lix-api:effect-creator effect_type:breathe selector:all description:"a very slow fade to warm white"
    • ➥ Uses effect-creator prompt (follow instructions in response)

  6. Troubleshoot a Light (Prompt):

    • @lix-api:troubleshooter selector:"id:d073d5xxxxxx"
    • ➥ Uses troubleshooter prompt

  7. List Your Lights (Tool):

    • "list my lights" or "list lights selector:all"
    • ➥ Uses list-lights tool

  8. Turn a Light On (Tool):

    • "turn on the lamp named Office Lamp" or "set state selector:label:Office Lamp power:on"
    • ➥ Uses set-state tool

  9. Set Color and Brightness (Tool):

    • "set the Kitchen group lights to blue at 50% brightness over 3 seconds"
    • "set state selector:group:Kitchen color:blue brightness:0.5 duration:3"
    • ➥ Uses set-state tool

  10. Toggle a Location (Tool):

    • "toggle the lights in the Living Room" or "toggle power selector:location:Living Room"
    • ➥ Uses toggle-power tool

  11. Increase Brightness (Tool):

    • "make all lights 10% brighter" or "state delta selector:all brightness:0.1"
    • ➥ Uses state-delta tool

  12. Activate a Scene (Requires Scene UUID from Resource/Tool):

    • "activate scene with uuid abcdef12-3456-..."
    • "activate scene scene_uuid:abcdef12-3456-..."
    • ➥ Uses activate-scene tool

Dockerfile

FROM node:18-alpine

WORKDIR /app

# Copy package files
COPY package*.json ./

# Install dependencies cleanly
# Using --omit=dev because devDependencies are not needed in production
RUN npm ci --omit=dev --production --no-fund --no-audit

# Copy the rest of the application code
COPY . .

# Set the entrypoint
ENTRYPOINT ["node", "lifx-api-mcp-server.js"]

# Default command (can be overridden, e.g., with API token if not using config/env)
# CMD ["YOUR_DEFAULT_TOKEN_IF_NEEDED"]

Disclaimer

  • This software is provided "as is", without warranty of any kind. Use at your own risk.
  • The author is not affiliated with LIFX (LiFi Labs Inc.).
  • Ensure you understand the LIFX API rate limits (120 requests/minute per token) to avoid temporary blocks. Rate limit information is logged if logLevel is verbose.
  • This server was partially generated with AI assistance and may contain bugs.

Support

If you find this tool useful, consider supporting the developer (optional):

Buy Me a Coffee | GitHub Sponsorship