xLights MCP Server
An MCP server for xLights that analyzes music, manages show data, generates/remaps light-show sequences, and integrates with FPP.
Manage xLights shows: list/add/switch show folders and list models, controllers, sequences, and effects.
Inspect existing sequences for song info, duration, models, and effects.
Analyze audio for beats, downbeats, tempo, song structure, energy, frequency spectrum, and optional source separation.
Generate .xsq sequences in auto, guided, or template modes with themes/palettes and vocal assignments; preview plans without writing files.
Import/remap community .xsq or .zip sequences to your layout with automatic model matching, overrides, and pixel thresholds.
Check FPP status, upload .fseq/audio, list/start playlists, and stop playback.
Allows interaction with the xLights MCP server through Windsurf (by Codeium) for music analysis and light show sequence generation.
Allows interaction with the xLights MCP server through GitHub Copilot CLI for music analysis and light show sequence generation.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@xLights MCP Server analyze beats.mp3 and generate a Halloween sequence"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
⚠️ Beta: This project is currently in beta. Features may change, and you may encounter bugs. Feedback and contributions are welcome!
xLights MCP Server
An MCP (Model Context Protocol) server that analyzes music and generates xLights light show sequences. Works with any MCP-compatible AI tool — GitHub Copilot CLI, Claude Desktop, Cursor, VS Code + Copilot Chat, Windsurf, Cline, and more.
Give it an .mp3, and it will analyze the beats, song structure, and energy — then generate a valid .xsq sequence file with effects placed across all of your light models, synced to the music
What It Does
🎵 Audio Analysis
Beat & tempo detection — percussion-aware beats, phase-aligned bars, conservative meter estimates, and local tempo changes
Song structure — beat-synchronized timbre/harmony changes and acoustic repetition, with heuristic section labels
Frequency spectrum — bass, mid, and high energy curves over time
Energy profiling — loudness dynamics, multiscale RMS, spectral flux/brightness, peak detection, and dynamic range
Source separation — isolate vocals, drums, bass, and other stems via Demucs (optional)
💡 Sequence Generation
Generates valid
.xsqfiles that open directly in xLights — no xLights GUI required during generationReads your actual show config — knows your models, controllers, channel counts, and model types
Intelligent effect selection — picks effects based on model type (arches get chases, trees get spirals, etc.) and musical features (beats → shockwaves, choruses → high energy, verses → gentle)
Theme-aware palettes — Christmas (red/green/gold) and Halloween (orange/purple) color schemes
Three generation modes:
Automatic — AI picks everything, you review in xLights
Guided — AI shows song structure, you choose effects per section
Template — define reusable effect recipes, AI places them on beat
Never overwrites — existing sequences are safe; generated files get a
(generated N)suffix
📦 Sequence Import & Remapping
Import community sequences — take any
.xsqor.zippackage from the xLights community and remap it to your show layoutIntelligent model matching — automatically maps imported models to yours by name, type, and pixel count
Zip package support — extracts audio, video, shader, and image assets; rewrites hardcoded file paths
Singing model awareness — singing face models only match to other singing models
Full mapping report — see exactly what matched, how, and what was skipped
Manual overrides — correct any mapping before the remapped sequence is generated
📡 FPP Integration
Check status of your Falcon Pi Player
Upload sequences (.fseq + audio) to FPP
Manage playlists — list, start, stop
Works with FPP's REST API
Related MCP server: io.github.peterkolbe/ableton-for-ai
Prerequisites
Python 3.11+ (Python 3.12 recommended for optional audio features)
uv (recommended) or pip
ffmpeg — for audio format handling (
brew install ffmpegon macOS,apt install ffmpegon Linux)xLights — installed with at least one show folder configured
Installation
Step 1: Clone the repository
git clone https://github.com/JohnBreault/xlights-mcp-server.git
cd xlights-mcp-serverStep 2: Create a virtual environment and install
uv venv --python 3.12
uv pip install -e .If you already created .venv with an unsupported Python version, remove it
and run uv venv --python 3.12 again. PyTorch wheels for separation and
lyrics may not be available for the newest Python releases, including 3.15.
Optional extras for enhanced features:
# Stem separation — isolates vocals/drums/bass for smarter sequencing (~2GB model download)
uv pip install -e ".[separation]"
# Lyrics/singing faces — transcribes vocals for lip-sync animation
uv pip install -e ".[lyrics]"
# Better beat detection
uv pip install -e ".[beats]"
# Everything
uv pip install -e ".[all]"The beats extra uses a pinned modernized madmom fork
with bundled models. Installing it requires GitHub access and a C compiler
(Xcode Command Line Tools on macOS, or Visual C++ Build Tools on Windows).
The models have a separate non-commercial license; see the fork's README.
Without this extra, core beat detection uses librosa.
Because this extra requires NumPy 2, if you add it to an environment that
already has separation or lyrics, upgrade the combined extras so PyTorch
is upgraded too (on platforms that support PyTorch 2.3 or later):
uv pip install --upgrade -e ".[separation,beats,lyrics]"Omit any extras you do not use.
On Intel macOS, separation and lyrics use PyTorch 2.2.x with NumPy 1.x
because newer PyTorch wheels are unavailable. The beats extra skips madmom on
Intel macOS because it requires NumPy 2, so beat detection uses the librosa
fallback there, including when installing all.
Step 3: Show folder configuration
On first run, the server auto-detects your xLights show folders by scanning common locations:
OS | Locations checked |
macOS |
|
Windows |
|
Linux |
|
It looks for directories containing xlights_rgbeffects.xml (the file xLights creates in every show folder).
If auto-detection doesn't find your folders, create or edit ~/.xlights-mcp/config.json:
{
"show_folders": {
"christmas": "/path/to/your/xLights/Christmas",
"halloween": "/path/to/your/xLights/Halloween"
},
"active_show": "christmas",
"fpp": {
"host": "fpp.local",
"port": 80
}
}Step 4: Connect to your AI tool
The server uses stdio transport — your AI tool launches it as a subprocess.
Add to ~/.copilot/mcp-config.json:
{
"mcpServers": {
"xlights": {
"command": "uv",
"args": ["run", "--directory", "/path/to/xlights-mcp-server", "xlights-mcp-server"]
}
}
}Restart Copilot CLI after saving.
Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
"mcpServers": {
"xlights": {
"command": "uv",
"args": ["run", "--directory", "/path/to/xlights-mcp-server", "xlights-mcp-server"]
}
}
}Restart Claude Desktop after saving.
Add to your VS Code settings.json:
{
"mcp": {
"servers": {
"xlights": {
"command": "uv",
"args": ["run", "--directory", "/path/to/xlights-mcp-server", "xlights-mcp-server"]
}
}
}
}Add to Cursor MCP settings (Settings → MCP Servers → Add):
Name: xlights
Command:
uvArgs:
run --directory /path/to/xlights-mcp-server xlights-mcp-server
Any tool that supports the Model Context Protocol can use this server. Point it at:
command: uv
args: run --directory /path/to/xlights-mcp-server xlights-mcp-server
transport: stdioReplace /path/to/xlights-mcp-server with the actual path where you cloned the repo.
Usage
Once connected, interact with the server through natural language in your AI tool. Here are some example workflows:
Explore your show
> List my xLights shows
> Switch to the Halloween show
> List all my light models
> Show me the controllers
> What sequences do I have?
> Inspect the "Deck The Halls" sequenceAnalyze a song
> Analyze the song ~/Music/Jingle Bell Rock.mp3
> Show me the song structure for ~/Music/Monster Mash.mp3
> Get the beat map for this song
> What's the energy profile look like?The existing audio tools keep their names and arguments. analyze_song includes
the same beat and spectrum models returned by get_beat_map and
get_energy_profile, with these additional fields:
Result | Additional fields | Units / interpretation |
Beats |
| Overlapping 10-second windows, approximately 5 seconds apart; |
Beats |
| Adjacent positive window estimates differing by more than 10%; |
Beats |
| Heuristic evidence scores (not calibrated probabilities), selected backend, and degraded-analysis diagnostics. |
Spectrum |
| Positive frame-to-frame magnitude changes, normalized to 0-1. |
Spectrum |
| Hz; rolloff marks 85% of cumulative spectral magnitude. |
Spectrum |
| Dimensionless 0-1 noise/tonality descriptor; silence is not evidence of audible noise. |
Spectrum |
| Normalized RMS smoothed over approximately 0.25, 2, and 8 seconds, capped for short clips. |
All new spectral/energy curves use the existing rms_times timeline in seconds.
Existing band names, max-normalized band/RMS curves, raw average_loudness, and
dynamic_range (maximum RMS divided by mean RMS) retain their meanings.
The detailed seven-band Python option remains available.
Meter inference considers simple two-, three-, and four-beat accent patterns. Ambiguous patterns, including indistinguishable two-/four-beat accents, retain four-beat bars with zero inference confidence; this does not prove a 4/4 time signature. Compound meters are not inferred. When installed and working, madmom supplies a coherent beat/downbeat grid instead. HPSS failures fall back to full-mix rhythm analysis with diagnostics. Onsets stay on attacks, without backtracking into preceding quiet audio.
Section boundaries use beat-synchronized MFCC/chroma, brightness, and RMS features.
Local novelty and acoustic repetition inform boundaries and labels; confident
bar positions (or the selected madmom grid) can refine boundary alignment.
Low-evidence audio falls back to conservative energy boundaries or one whole-file
section. Silence returns an unknown section with zero confidence. Labels are
estimates, not guaranteed verse/chorus annotations; too few sections retain
energy-based labeling. All timestamps remain on the original, untrimmed audio
timeline. Sequence generation automatically consumes the improved beats,
downbeats, and sections; it does not yet use the local tempo curve or additional
spectral descriptors directly.
Full analysis (including generation/previews) decodes the full mix once on a cache
miss and persists validated core results under AudioConfig.cache_dir (default
~/.xlights-mcp/audio_cache/). Cache keys include file contents, sample rate,
analysis version, and relevant dependency versions. Writes are atomic; corrupt
or inaccessible caches are logged and recomputed. Transient enhancement failures
are not persisted as authoritative results. Optional stems are reevaluated outside
the core cache, so newly available stems are not hidden by a previous analysis.
Standalone beat/structure/energy tools analyze only the requested data and do not
use the full-analysis cache. No source audio or show configuration is modified.
These features use existing librosa/NumPy dependencies; no additional package, service, or model is required. Invalid or undecodable audio produces an explicit error dictionary from the audio MCP tools.
Generate a sequence
> Create a sequence for ~/Music/Jingle Bell Rock.mp3
> Create a sequence for ~/Music/Jingle Bell Rock.mp3 using red and green colors
> Preview what a sequence would look like for this song before creating itWhen generating, you'll be asked to choose a mode:
auto — fully automatic, AI picks effects and colors
guided — see the song structure first, then choose effects per section
template — apply saved effect recipes to detected sections
Import a community sequence
> Import the sequence ~/Downloads/Holly Jolly Christmas SD.zip to my show
> Import ~/Downloads/Christmas Time.xsq and show me the model mapping
> Import this sequence but map "Arch Left" to my "Arches-1" modelThe importer supports both standalone .xsq files and .zip packages (which include audio, video assets, and the source show's model data). It automatically matches models from the imported sequence to your layout using:
Exact name match → identical model names
Similar words → shared words like "snowflake", "arch", "tree"
Model type → same
display_astype (e.g., both Arches)Pixel count → within 70% of each other
Manual overrides → you choose specific mappings
Manage FPP (when controllers are online)
> Check the FPP status
> List playlists on FPP
> Start the Christmas playlist
> Stop playbackAvailable Tools
Show Management
Tool | Description |
| List all configured xLights show folders |
| Switch the active show folder |
| List all light models with type, controller, and category info |
| List controllers with IPs, protocols, and channel counts |
| List all |
| Show song info, duration, effects, and models used in a sequence |
| List all available xLights effects with descriptions |
Audio Analysis
Tool | Description |
| Full audio analysis: beats, structure, spectrum, energy |
| Detect verse/chorus/bridge/intro/outro sections |
| Get beat timestamps, downbeats, tempo, and onsets |
| Get loudness curve and bass/mid/high frequency band energy |
Sequence Generation
Tool | Description |
| Generate a |
| Preview the generation plan without writing a file |
Sequence Import & Remapping
Tool | Description |
| Import a |
FPP Integration
Tool | Description |
| Check FPP connection and playback state |
| Upload |
| List all playlists on FPP |
| Start a playlist (with optional repeat) |
| Stop current playback |
How It Works
Effect Selection Logic
The server maps model types to appropriate effects:
Model Type | Best Effects |
Arches | SingleStrand, Chase, ColorWash, Morph |
Tree | Spirals, Pinwheel, Meteors, Circles |
Single Line | Chase, Morph, SingleStrand, Shimmer |
Poly Line | Chase, SingleStrand, Twinkle, Morph |
Window Frame | Marquee, ColorWash, On, Curtain |
Custom shapes | Shockwave, Circles, Plasma, Twinkle, Warp |
And maps musical features to effect choices:
Musical Feature | Effects |
Strong beats | Shockwave, Morph, Strobe |
Rhythmic passages | SingleStrand, Chase, Bars, Marquee |
High energy (chorus) | Chase, Meteors, SingleStrand |
Low energy (verse) | Twinkle, Shimmer, ColorWash, Snowflakes |
Sustained notes | Plasma, Pinwheel, Spirals, Galaxy |
Transitions | Warp, Curtain, Morph |
Intro/Outro | Curtain, ColorWash, Twinkle |
File Format
Generated .xsq files are standard xLights XML containing:
<head>— song metadata, media file path, duration, timing (25ms frames)<ColorPalettes>— themed color palettes for effects<EffectDB>— deduplicated effect parameter definitions<DisplayElements>— all models included in the sequence<ElementEffects>— effect placements per model, per layer, with timing
Project Structure
xlights-mcp-server/
├── pyproject.toml
├── README.md
├── src/xlights_mcp/
│ ├── server.py # MCP server entry point & tool definitions
│ ├── config.py # Configuration management
│ ├── audio/
│ │ ├── analyzer.py # Full analysis pipeline orchestrator
│ │ ├── cache.py # Versioned core-analysis cache
│ │ ├── beats.py # Beat/tempo/onset detection (librosa + madmom)
│ │ ├── structure.py # Song section detection (verse/chorus/bridge)
│ │ ├── spectrum.py # Frequency band & energy analysis
│ │ └── separator.py # Demucs stem separation (optional)
│ ├── xlights/
│ │ ├── show.py # Show folder parser (networks + models XML)
│ │ ├── xsq_reader.py # Parse existing .xsq sequences
│ │ ├── xsq_writer.py # Generate .xsq XML files
│ │ ├── effects.py # Effect library & model/music mappings
│ │ ├── palettes.py # Color palette definitions & themes
│ │ └── models.py # Data models (Controller, LightModel, etc.)
│ ├── sequencer/
│ │ └── engine.py # Sequence generation engine (auto/guided/template)
│ └── fpp/
│ ├── client.py # FPP REST API client
│ ├── upload.py # Sequence upload to FPP
│ └── schedule.py # Schedule management
└── tests/Troubleshooting
MCP server not loading
Verify your MCP config file is valid JSON (no comments, no trailing commas)
Check the
--directorypath points to the repo root (wherepyproject.tomlis)Restart your AI tool after config changes
Test manually:
cd /path/to/xlights-mcp-server && uv run xlights-mcp-server— should start without errors
"No xLights show folders found"
Make sure xLights is installed and you've opened it at least once (it creates
xlights_rgbeffects.xmlin each show folder)If your show folder is in a non-standard location, add it to
~/.xlights-mcp/config.json
"No models found" error
Verify the show folder contains
xlights_networks.xmlandxlights_rgbeffects.xmlUse
list_showsto check which show is active and whether the path exists
Audio analysis is slow
First run downloads librosa data (~10MB); subsequent runs are faster
Demucs stem separation takes 30-60s per song on CPU; results are cached
Without optional deps, analysis takes ~5s per song
Generated sequence looks wrong in xLights
The
.xsqis a starting point — tweak effects, timing, and palettes in xLightsUse
inspect_sequenceto review what was generated before opening
FPP connection fails
Verify FPP is powered on and on the same network
Check the hostname/IP in
~/.xlights-mcp/config.jsonFPP tools gracefully report connection errors; core generation works fully offline
License
MIT
Audio-analysis research provenance
The deterministic audio capabilities were compared with
twinklr at commit 59bd7e4.
That snapshot has no identified license granting source-code reuse. This project
therefore implements standard DSP techniques independently using
librosa's documented APIs, rather than copying
or translating twinklr source, tests, bespoke scoring rules, or tuned constants.
Twinklr is not a dependency, and this acknowledgment does not grant rights to its
code. Its LLM profiling, remote lyrics/metadata services, and optional MIR model
backends are not included.
Available Tools
20 toolsadd_show_folderA
Add an xLights show folder by path.
Use this to confirm a detected show folder or provide a custom path. The folder must contain an xlights_rgbeffects.xml file.
Args: path: Full filesystem path to the xLights show folder name: Optional display name for the show (derived from folder name if omitted)
Inputs: path (required), name.
analyze_songB
Analyze a music file for light show sequencing.
Performs full audio analysis: beat detection, song structure, frequency spectrum, energy profile, and optionally source separation.
Args: mp3_path: Path to the .mp3 file to analyze
Inputs: mp3_path (required).
create_sequenceA
Create an xLights sequence from a music file.
Analyzes the audio and generates a .xsq file with effects placed on your light models according to the selected generation mode.
Args: mp3_path: Path to the .mp3 file mode: Generation mode — "auto" (AI picks everything), "guided" (interactive), or "template" (apply saved recipes) palette_hint: Optional color hint (e.g., "red and green", "orange and purple") theme: Optional theme hint (e.g., "christmas", "halloween", "energetic") vocal_assignments: Optional mapping of model names to vocal track names. Use {"all": "<track_name>"} to assign one track to all singing models, or map individual models like {"Snowman": "Vocals", "Bulb Blue": "Full Mix Vocals"}. If omitted and singing models are detected, returns available models and tracks so you can prompt the user for assignments. show_name: Which show folder to generate the sequence in (e.g., "christmas", "halloween"). If omitted and multiple shows exist, returns available shows so you can ask the user which one to use.
Inputs: mp3_path (required), mode, theme, show_name, +2 more.
fpp_list_playlistsA
List all playlists on the Falcon Pi Player.
Inputs: no named parameters.
fpp_start_playlistC
Start a playlist on the Falcon Pi Player.
Args: playlist_name: Name of the playlist to start repeat: Whether to loop the playlist
Inputs: playlist_name (required), repeat.
fpp_statusA
Check Falcon Pi Player connection status and current state.
Returns FPP version, current playlist, scheduler state, etc.
Inputs: no named parameters.
fpp_stopB
Stop current playback on the Falcon Pi Player.
Inputs: no named parameters.
fpp_upload_sequenceC
Upload a sequence (.fseq) and optional audio to Falcon Pi Player.
Args: fseq_path: Path to the .fseq file to upload audio_path: Optional path to the audio file (.mp3/.ogg)
Inputs: fseq_path (required), audio_path.
get_beat_mapC
Get beat and downbeat timestamps for a song.
Args: mp3_path: Path to the .mp3 file
Inputs: mp3_path (required).
get_energy_profileB
Get energy and frequency band analysis for a song.
Returns loudness curve and bass/mid/high energy over time.
Args: mp3_path: Path to the .mp3 file
Inputs: mp3_path (required).
get_song_structureC
Get the verse/chorus/bridge structure of a song.
Args: mp3_path: Path to the .mp3 file
Inputs: mp3_path (required).
inspect_sequenceA
Inspect an existing xLights sequence file.
Shows the song info, duration, models used, and effect summary.
Args: sequence_name: Name of the sequence (without .xsq extension)
Inputs: sequence_name (required).
list_controllersA
List all controllers configured in the active xLights show.
Returns controller names, IPs, protocols, and channel counts.
Inputs: no named parameters.
list_effectsA
List all available xLights effects with descriptions.
Returns effect names, descriptions, and which model types they work best on.
Inputs: no named parameters.
list_modelsB
List all light models in the active xLights show.
Returns model names, types, controller assignments, and channel info.
Inputs: no named parameters.
list_sequencesA
List all sequences (.xsq files) in the active show folder.
Inputs: no named parameters.
list_showsA
List all configured xLights show folders.
Returns the available show folders (e.g., Christmas, Halloween) and indicates which one is currently active.
Inputs: no named parameters.
preview_planA
Preview the sequence generation plan without creating a file.
Shows what effects would be placed on which models, based on the audio analysis and selected mode.
Args: mp3_path: Path to the .mp3 file mode: Generation mode — "auto", "guided", or "template" show_name: Which show folder to preview against. If omitted and multiple shows exist, returns available shows so you can ask the user.
Inputs: mp3_path (required), mode, show_name.
remap_sequenceA
Import a sequence from a different show layout and remap it to your models.
Accepts a .xsq file or .zip package from the xLights community. Automatically matches imported models to your show's models using name similarity, model type, and pixel count. Generates a new .xsq with effects remapped to your layout.
Args: import_path: Path to the .xsq or .zip file to import. overrides: Optional dict mapping imported model names to your model names. These take precedence over automatic matching. pixel_threshold: Similarity threshold for pixel count matching (0.0-1.0). Default 0.70 means models must have at least 70% pixel count similarity. show_name: Which show folder to import into (e.g., "christmas", "halloween"). If omitted and multiple shows exist, returns available shows so you can ask the user which one to use.
Returns: Dict with mapping report, output path, and summary statistics.
Inputs: import_path (required), overrides, show_name, pixel_threshold.
switch_showC
Switch the active xLights show folder.
Args: show_name: Name of the show to activate (e.g., "christmas", "halloween")
Inputs: show_name (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 20 tools
Most tools target clearly distinct resources or actions (show management, sequence inspection, FPP control). The main overlap is analyze_song, which aggregates beat, structure, and energy analysis that are also exposed as separate tools, though the descriptions clarify the distinction.
The set predominantly uses snake_case verb_noun names such as switch_show, list_models, create_sequence, and remap_sequence. Minor deviations like fpp_status and fpp_stop are acceptable because the fpp_ prefix consistently groups FPP-related tools.
With 20 tools, the surface is broad but near the heavy end for a single MCP server. The tools are mostly justified by the domain, but the aggregate/granular audio-analysis tools add some duplication that inflates the count.
The server covers the core workflow well: audio analysis, show/model/sequence inspection, sequence generation and preview, remapping, upload to FPP, and playlist control. Minor gaps remain, such as no sequence deletion/update, no FPP playlist creation, and no explicit fseq rendering/export step.
Maintenance
Related MCP Connectors
Create, co-edit, analyze, publish, and export collaborative step-sequencer sessions through MCP.
MCP server for Producer/Riffusion AI music generation
Create and track AI music videos and audio-reactive visuals from songs.
Generate AI music via the Lacuna Music API from MCP clients like Claude Desktop & Code.
Related MCP Servers
- AlicenseBqualityCmaintenanceConnects Ableton Live to AI through MCP, enabling prompt-assisted music production with extended tools and a 33-personality style system for generating parts in various artist styles.6251 PyPI5MIT
- AlicenseAqualityDmaintenanceMCP server that bridges Ableton Live with AI models, enabling real-time project inspection and control such as track overview, device parameters, and audio analysis.1273 PyPI1MIT
- AlicenseNot gradedqualityAmaintenanceConnects AI/LLM tools to Ableton Live through 440+ MCP tools spanning tracks, clips, devices, mixer, MIDI mapping, plugin management, video integration, setlists, performance monitoring, and audio analysis. Enables natural-language music production and real-time live show control, including scene firing, preset recall, and emergency stop.MIT
- AlicenseCqualityBmaintenanceEnables Claude or any AI agent to operate Live 12 Intro end to end: creating tracks and scenes, writing and quantizing MIDI clips, loading audio onto the Arrangement timeline, setting device parameters in real units, drawing clip automation, mixing with real sidechain, and rendering or analyzing audio so the agent can check its own work. It exposes 57 tools over MCP or a local JSON socket, working within the stock Intro edition's 16-track, 16-scene limits.57MIT