⚠️ 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
• Works with FPP's REST API

Prerequisites

• Python 3.11+
• uv (recommended) or pip
• ffmpeg — for audio format handling (brew install ffmpeg on macOS, apt install ffmpeg on 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-server

Step 2: Create a virtual environment and install

uv venv
uv pip install -e .

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]"

Step 3: Show folder configuration

On first run, the server auto-detects your xLights show folders by scanning common locations:

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.

{
  "mcpServers": {
    "xlights": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/xlights-mcp-server", "xlights-mcp-server"]
    }
  }
}

{
  "mcpServers": {
    "xlights": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/xlights-mcp-server", "xlights-mcp-server"]
    }
  }
}

{
  "mcp": {
    "servers": {
      "xlights": {
        "command": "uv",
        "args": ["run", "--directory", "/path/to/xlights-mcp-server", "xlights-mcp-server"]
      }
    }
  }
}

command: uv
args: run --directory /path/to/xlights-mcp-server xlights-mcp-server
transport: stdio

Replace /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" sequence

Analyze 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?

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 it

When 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" model

The 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:

1. Exact name match → identical model names
2. Similar words → shared words like "snowflake", "arch", "tree"
3. Model type → same display_as type (e.g., both Arches)
4. Pixel count → within 70% of each other
5. 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 playback

Available Tools

Show Management

Audio Analysis

Sequence Generation

Sequence Import & Remapping

FPP Integration

How It Works

Effect Selection Logic

The server maps model types to appropriate effects:

And maps musical features to effect choices:

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
│   │   ├── 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 --directory path points to the repo root (where pyproject.toml is)
• 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.xml in 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.xml and xlights_rgbeffects.xml
• Use list_shows to 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 .xsq is a starting point — tweak effects, timing, and palettes in xLights
• Use inspect_sequence to 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.json
• FPP tools gracefully report connection errors; core generation works fully offline

License

MIT