README
¶
lifx
LIFX Light TUI and MCP Server
A gorgeous terminal UI and MCP server for controlling LIFX lights. Built with Charm (Bubble Tea + Lip Gloss) with support for both LAN and Cloud API backends.
Features
- Dual Backend: supports both LAN protocol and LIFX Cloud API.
- Groups & Lights: rooms/groups with per-light controls.
- Brightness, Color, Kelvin: keyboard-driven adjustments.
- Scenes: activate saved scenes via the API backend.
- Search: filter lights by name.
- MCP Server: integrate with AI agents via the Model Context Protocol.
Install
Via Go:
go install github.com/blacktop/lifx@latest
Via Homebrew
brew install blacktop/tap/lifx
Backend selection
- Default is auto: tries API if
LIFX_API_KEYis set, otherwise uses LAN. - Force backend with
--backend:
lifx --backend lan
lifx --backend api --api-key "$LIFX_API_KEY"
Environment
Get your API key from cloud.lifx.com/settings:
export LIFX_API_KEY=... # Required for API backend and MCP server
Configuration
Customize color presets by creating a config file:
| Platform | Location |
|---|---|
| macOS | ~/Library/Application Support/lifx/config.yaml |
| Linux | ~/.config/lifx/config.yaml |
| Windows | %AppData%\lifx\config.yaml |
Example config with custom presets:
presets:
- name: Sunrise
hue: 35
saturation: 80
kelvin: 2500
- name: Daylight
hue: 0
saturation: 0
kelvin: 5500
- name: Red
hue: 0
saturation: 100
kelvin: 3500
- name: Green
hue: 120
saturation: 100
kelvin: 3500
See docs/config.example.yaml for a complete example.
Keybindings
Navigation
| Key | Action |
|---|---|
j / ↓ |
Move down |
k / ↑ |
Move up |
Tab |
Toggle side panel |
Light Control
| Key | Action |
|---|---|
Space |
Toggle power |
0-9 |
Set brightness to 10-100% |
h/l |
Decrease/increase brightness |
p |
Cycle color preset |
w/c |
Warmer/cooler temperature |
Group Control
| Key | Action |
|---|---|
a |
Turn all lights in group on |
x |
Turn all lights in group off |
Other
| Key | Action |
|---|---|
/ |
Search lights |
s |
Scenes modal |
r |
Refresh |
q |
Quit |
MCP Server
Run lifx as an MCP (Model Context Protocol) server for AI agent integration:
lifx mcp
Available Tools
| Tool | Description |
|---|---|
list_lights |
List all lights with current state (power, brightness, color) |
set_power |
Turn a specific light on or off |
set_all_power |
Turn all lights on or off |
set_brightness |
Set brightness level (0-100) |
set_color |
Set hue, saturation, brightness, and/or kelvin |
list_scenes |
List all available scenes |
activate_scene |
Activate a scene by ID |
Configuration
Claude Code
claude mcp add lifx -e LIFX_API_KEY=your_api_key -- lifx mcp
Codex CLI
codex mcp add lifx --env LIFX_API_KEY=your_api_key -- lifx mcp
Gemini CLI
gemini mcp add lifx lifx mcp -e LIFX_API_KEY=your_api_key
Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"lifx": {
"command": "lifx",
"args": ["mcp"],
"env": {
"LIFX_API_KEY": "your_api_key"
}
}
}
}
Testing
make mcp-test
Notes
- LAN protocol requires lights to be on the same network.
- MCP server and scenes require the LIFX Cloud API (
LIFX_API_KEY).
License
MIT Copyright (c) 2025 blacktop
Documentation
¶
Overview ¶
Copyright © 2025 blacktop
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Source Files
Directories