Mixx-DJ-MCP
by sandraschi
README.md
<div align="center">
<br/>
<h1>Mixx-DJ-MCP</h1>
<p><strong>AI-native DJ control for Mixxx.</strong> 80+ operations across decks, library, effects, mixer, stems, transitions, video, and more. Talk to your DJ software like a colleague.</p>
<br/>
[](https://github.com/sandraschi/mixx-dj-mcp)
[](LICENSE)
[](https://python.org)
[](https://github.com/jlowin/fastmcp)
[](https://mixxx.org)
[](https://react.dev)
[](https://tauri.app)
[](https://nsis.sourceforge.io)
<br/>
<b>Say:</b> <i>"Load Daft Punk on deck 2, sync it, cue the drop, then fade in on the next beat."</i>
<br/>
<b>It happens.</b>
<br/><br/>
<img src="docs/screenshots/cockpit.png" alt="Mixx-DJ-MCP Cockpit" width="800"/>
<br/>
<sub>
<a href="docs/FIRST-RUN.md">First Run</a> ·
<a href="docs/INSTALL.md">Install</a> ·
<a href="docs/TOOLS.md">Tools</a> ·
<a href="docs/STATUS.md">Status</a> ·
<a href="docs/ARCHITECTURE.md">Architecture</a> ·
<a href="docs/MIXXX_VIDEO.md">Video</a> ·
<a href="docs/ORCHESTRATOR.md">AV Rig</a> ·
<a href="docs/NDI.md">NDI</a> ·
<a href="docs/NDI-TARGETS.md">NDI Targets</a> ·
<a href="docs/NOOB_GUIDE.md">Beginner Guide</a> ·
<a href="docs/AI_TRANSITIONS.md">AI Transitions</a>
</sub>
</div>
<br/>
## One command to start
```bash
uv sync && uv run uvicorn mixx_dj_mcp.server:app --port 11116
```
Configure Mixxx OSC once (one minute): **Preferences > MIDI/OSC > Enable OSC**, set out `11118`, in `11119`, send to `127.0.0.1`, restart. Done.
Your AI assistant (Claude, Cursor, opencode) can now control your decks.
## What it does
| You say | The AI does |
|---------|-------------|
| "Play deck 2" | `mixx_deck(operation="play_pause", deck=2)` — OSC to Mixxx |
| "Find some 128 BPM tech house" | `mixx_library(operation="search", query="tech house")` |
| "Add reverb to the outgoing track" | `mixx_effects(operation="chain_load", rack=1, effect="Reverb")` |
| "Plan a 30-min drum & bass set" | `mixx_ai_set(operation="plan", style="drum and bass")` |
| "Record this set" | `mixx_recording(operation="start")` |
| "Analyse this track's key" | `mixx_analyze(operation="track", path="C:/Music/track.mp3")` |
| "Show me my most-played tracks" | `mixx_history(operation="profile")` |
| "Transition with an echo out" | `mixx_transition(operation="apply", effect="echo_out")` |
## Tools at a glance
| Tool | What it controls |
|------|-----------------|
| `mixx_deck` | Play/pause, load, cue, loops, sync, rate, scratch, hotcues, quantize, keylock — plus video |
| `mixx_library` | Search, browse crates/playlists, BPM/key metadata |
| `mixx_effects` | Effect chains, parameters, quick effects, super knob |
| `mixx_mixer` | Crossfader, EQ, gain, headphone cue, talkover, mic |
| `mixx_analyze` | BPM detection, musical key (Krumhansl-Schmuckler), energy, cue suggestions |
| `mixx_stems` | Demucs stem separation, sampler loading, stem-aware mixing |
| `mixx_transition` | AI-suggested transitions, 8 effect types, auto-crossfader |
| `mixx_ai_set` | **Autonomous DJ** — plan sets, perform transitions, review |
| `mixx_recording` | Record, replay, and export DJ sets as OSC streams |
| `mixx_history` | Play history, style profile, track suggestions |
| `mixx_crate` | LLM-generated smart crates by BPM/key/genre |
| `mixx_set` | Harmonic mixing sequences, energy curve planning |
| `mixx_skin` | List, apply, create video skins, AI palette generation |
| `mixx_vinyl` | OCR catalog, AI gig picker, Plex crossref |
| `mixx_controller` | USB auto-detect, install mappings |
| `mixx_daw` | Export stems to DaVinci Resolve, Reaper |
| Prefab cards | `show_deck/mixer/library_status_card` — rich in-chat UI |
## Quick links
| For... | Read |
|--------|------|
| **Installing** the server, webapp, NSIS installer, or MCPB | [`docs/INSTALL.md`](docs/INSTALL.md) |
| **Status & backlog** | [`docs/STATUS.md`](docs/STATUS.md) · [`docs/TODO.md`](docs/TODO.md) |
| **Full tool reference** with parameters, returns, and examples | [`docs/TOOLS.md`](docs/TOOLS.md) |
| **Using video** — requires the mixxxxx fork of Mixxx | [`docs/MIXXX_VIDEO.md`](docs/MIXXX_VIDEO.md) |
| **AV orchestrator** (mixxxxx hub, NDI, Resolume, OBS) | [`docs/ORCHESTRATOR.md`](docs/ORCHESTRATOR.md) · webapp **Help → AV Rig** |
| **NDI** (network video from mixxxxx) | [`docs/NDI.md`](docs/NDI.md) · [`docs/NDI-TARGETS.md`](docs/NDI-TARGETS.md) · webapp **Help → NDI** |
| **Project status & backlog** | [`docs/STATUS.md`](docs/STATUS.md) · [`docs/TODO.md`](docs/TODO.md) |
| **AI-powered transitions** between decks | [`docs/AI_TRANSITIONS.md`](docs/AI_TRANSITIONS.md) |
| **Architecture** — how the OSC bridge, REST API, and webapp work | [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) |
| **Beginner's guide** to DJing with Mixxx | [`docs/NOOB_GUIDE.md`](docs/NOOB_GUIDE.md) |
| **Comparing** Mixxx to other DJ software | [`docs/DJ_LANDSCAPE.md`](docs/DJ_LANDSCAPE.md) |
| **Algoriddim djay** feature parity | [`docs/ALGORIDDIM_COMPARISON.md`](docs/ALGORIDDIM_COMPARISON.md) |
| **Mixxx OSC setup** and address reference | [`bridge/README.md`](bridge/README.md) |
## Video DJing
Mixx-DJ-MCP supports the **mixxxxx** video fork — a modified Mixxx build that adds FFmpeg video playback, per-deck video widgets, and fullscreen projector output alongside the standard audio engine.
[mixxxxx on GitHub](https://github.com/sandraschi/mixxxxx) · [`docs/MIXXX_VIDEO.md`](docs/MIXXX_VIDEO.md)
## Ports
| Port | What |
|------|------|
| **11116** | Backend REST API + MCP transport |
| **11117** | React webapp (Vite) |
| **11118** | OSC feedback from Mixxx |
| **11119** | OSC commands to Mixxx |
## Fleet integrations
Mixx-DJ-MCP is a **Fleet Audio Hub** — it connects to other MCP servers for a unified DJ ecosystem:
| Server | Integration |
|--------|-------------|
| `plex-mcp` | Cross-reference vinyl with digital library |
| `songgeneration-mcp` | AI music generation loaded direct to decks |
| `sfx-mcp` | Sound effects triggered during live sets |
| `vfx-mcp` | Real-time video effects on video output |
| `stems-mcp` | External stem separation engine |
| `davinci-resolve-mcp` | Export stems to Fairlight for post-production |
| `reaper-mcp` | Export stems to Reaper DAW |
| `inkscape-mcp` | AI skin colour palette generation |
| `speech-mcp` | Voice-controlled DJing ("Hey Mixxx, load deck 2...") |
## License
MIT — Sandra Schipal
_Vinyl not included. Mixxx not included. Bad music taste is your own._TDQS
B3.4/5.0
Scored across 19 tools
Disambiguation3/5
Most tools are cleanly scoped by domain (deck, mixer, effects, library, crates), but the AI-set trio—mixx_set, mixx_ai_set, and mixx_transition—overlap heavily on set planning and transition suggestion/execution, and mixx_stems also exposes a 'transition' op. mixx_analyze and mixx_library both surface track BPM/key metadata. Descriptions help, but boundaries require careful reading.
Naming Consistency4/5
The bulk of tools follow a consistent 'mixx_<domain>' snake_case pattern that maps cleanly to their domain. The three 'show_<x>_status_card' tools deviate from that prefix convention, introducing a second pattern, but it remains readable and predictable overall.
Tool Count4/5
19 tools is on the higher side, but the portmanteau design means each tool represents a genuine distinct domain (deck, mixer, effects, stems, vinyl, recording, etc.), so each earns its place. Slightly heavy but well justified for a full DJ control surface.
Completeness4/5
Coverage is broad and deep—transport, mixing, effects, library, crates, skins, stems, transitions, recording, history, and even DAW export. Minor gaps exist (e.g., beatgrid/sample editing, finer controller mapping edits), but core workflows and lifecycle operations are well covered.
Maintenance
ActivityActive
ResponsivenessNo issues