⚠️ 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 — identifies every beat, downbeat, and bar boundary
• Song structure — detects intro, verse, chorus, bridge, and outro sections
• Frequency spectrum — bass, mid, and high energy curves over time
• Energy profiling — loudness dynamics, peak detection, dynamic range
• Source separation — isolate vocals, drums, bass, and other stems via Demucs (optional)

💡 Sequence Generation

• Generates valid .xsq files that open directly in xLights — no xLights GUI required during generation
• Reads 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 .xsq or .zip package from the xLights community and remap it to your show layout
• Intelligent 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