# LIFX MCP Server
A Model Context Protocol (MCP) server that provides tools for controlling LIFX smart lights through the LIFX HTTP API.
## Features
This MCP server exposes the following LIFX API functionality as tools:
- 🔍 **list_lights** - Get all lights or filter by selector
- ⚡ **set_state** - Control power, color, brightness of lights
- 🔄 **toggle_power** - Toggle lights on/off
- 🫁 **breathe_effect** - Create breathing light effects
- 💫 **pulse_effect** - Create pulsing light effects
- 🎬 **list_scenes** - List all saved scenes
- ▶️ **activate_scene** - Activate a specific scene
- ✅ **validate_color** - Validate color string formats
- ⏹️ **effects_off** - Turn off any running effects
### 🎨 Interactive MCP App
NEW! This server includes an interactive web-based UI that provides:
- Visual controls for all your LIFX lights
- Real-time power, color, and brightness adjustments
- One-click color presets
- Visual effects (breathe & pulse) controls
- Theme-aware design that adapts to your client
See [MCP_APP_GUIDE.md](MCP_APP_GUIDE.md) for details on using the interactive UI.
## Prerequisites
1. **LIFX API Token**: Get your token from [LIFX Cloud Settings](https://cloud.lifx.com/settings)
2. **Node.js**: Version 16 or higher
3. **VS Code** with **GitHub Copilot** extension
## Installation
1. Clone this repository:
```bash
git clone https://github.com/lenvolk/mcp-lifx.git
cd mcp-lifx
```
2. Install dependencies:
```bash
npm install
```
3. Build the project:
```bash
npm run build
```
## Usage
### With VS Code and GitHub Copilot
The LIFX MCP server works seamlessly with VS Code's GitHub Copilot:
1. Ensure the server is built: `npm run build`
2. Set your `LIFX_API_TOKEN` environment variable
3. The server will be automatically discovered by VS Code's MCP integration
4. Open GitHub Copilot Chat and interact with your lights
Example interactions:
- "List all my LIFX lights"
- "Open LIFX control" - launches the interactive UI with visual controls
- "Show LIFX app" - alternative way to open the control interface
- "Turn on the kitchen lights"
- "Set living room lights to blue"
- "Launch LIFX dashboard" - opens the visual control panel
### Running the Server
You can run the server directly with:
```bash
npm start
```
Or in development mode:
```bash
npm run serve
```
## Example Usage
Once connected to an MCP client, you can use commands like:
### Text Commands
- "List all my LIFX lights"
- "Turn on the kitchen lights"
- "Set living room lights to blue"
- "Start a breathe effect on all lights with red color"
- "Show me all my saved scenes"
- "Activate the movie night scene"
### Interactive UI
Launch the visual control interface with any of these prompts:
- "Open LIFX control" - Primary command to launch the UI
- "Show LIFX app" - Alternative prompt
- "Launch LIFX interface" - Opens the interactive controls
- "Open LIFX dashboard" - Displays the visual UI
- "Show me LIFX controls" - Launches the control panel
- "Open the LIFX control panel" - Starts the interactive interface
- "I want to control my LIFX lights visually" - Opens the UI
- "Show LIFX remote" - Alternative way to access controls
The interactive UI provides visual controls for power, brightness, colors, and effects without needing text commands. See [MCP_APP_GUIDE.md](./MCP_APP_GUIDE.md) for details.
## LIFX Selectors
Use selectors to target specific lights:
- `all` - All lights
- `label:Kitchen` - Lights labeled "Kitchen"
- `group:Living Room` - Lights in "Living Room" group
- `location:Home` - Lights at "Home" location
- `id:d073d5000000` - Specific light by ID
## Color Formats
The server supports various color formats:
- **Named colors**: `red`, `blue`, `green`, `purple`, etc.
- **RGB**: `rgb:255,0,0` (red)
- **HSB**: `hue:120 saturation:1.0 brightness:0.5`
- **Kelvin**: `kelvin:3500` (warm white)
## Development
### Project Structure
```
mcp-lifx/
├── src/
│ ├── index.ts # Main MCP server implementation
│ ├── mcp-app.tsx # React MCP app UI
│ └── mcp-app.html # HTML entry point for app
├── build/
│ ├── index.js # Compiled server
│ └── src/
│ └── mcp-app.html # Bundled single-file app UI
├── LIFX.md # LIFX API documentation
├── MCP_APP_GUIDE.md # Interactive UI usage guide
├── mcp.md # MCP tutorial reference
├── vite.config.ts # Vite build configuration
├── package.json # Project configuration
├── tsconfig.json # TypeScript configuration
└── README.md # This file
```
### Available Scripts
- `npm run build` - Build both the MCP app UI and server
- `npm run build:app` - Build only the React UI
- `npm run build:server` - Build only the TypeScript server
- `npm start` - Run the compiled server
- `npm run serve` - Run server in development mode (with tsx)
- `npm run dev` - Build and run in one command
- `npm run clean` - Remove build directory
- `npm run rebuild` - Clean and rebuild everything
### API Reference
All LIFX API endpoints and parameters are documented in [LIFX.md](./LIFX.md).
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request
## License
ISC License
## Support
For issues with this MCP server, please open an issue on GitHub.
For LIFX API issues, refer to the [official LIFX API documentation](https://api.developer.lifx.com/).
---
**Note**: This is an unofficial LIFX MCP server. LIFX is a trademark of LIFX Pty Ltd.
