mixxx-mcp

MCP (Model Context Protocol) server for Mixxx DJ Software. Lets AI agents (Claude, Claude Code, etc.) control Mixxx in real time — transport, mixing, EQ, loops, hotcues, effects.

Architecture

AI Agent (Claude)
      │
      ▼ MCP tools
mixxx-mcp Python Server
      │                     ┌─────────────────────┐
      ├─ MIDI CC out ───────▶│ Virtual MIDI port   │
      │                     │ "mixxx-mcp"          │
      │                     └────────┬────────────┘
      │                              ▼ CC → engine.setValue()
      │                     ┌────────────────────┐
      │                     │ Mixxx + mixxx-mcp  │
      │                     │ .js controller      │
      │                     │ script              │
      ◀── OSC UDP ──────────┤ broadcasts state    │
   OscStateStore            └────────────────────┘

Write path: mcp.tool → MidiBridge → rtmidi CC → Mixxx JS script → engine.setValue()
Read path: Mixxx JS → OSC UDP → OscStateStore → mcp.tool → AI

Related MCP server: ableton-mcp-server

Setup

1. Install Python server

pip install -e ".[dev]"
# or without dev deps:
pip install mcp python-osc python-rtmidi

2. Install Mixxx controller script

Copy both files to your Mixxx controllers directory:

# macOS
cp mixxx-mcp.js mixxx-mcp.midi.xml \
  ~/Library/Containers/org.mixxx.mixxx/Data/Library/Application\ Support/Mixxx/controllers/

# Linux
cp mixxx-mcp.js mixxx-mcp.midi.xml ~/.mixxx/controllers/

# Windows
cp mixxx-mcp.js mixxx-mcp.midi.xml %LOCALAPPDATA%\Mixxx\controllers\

3. Enable in Mixxx

1. Open Mixxx → Preferences → Controllers

2. Select mixxx-mcp from the device list

3. Check Enable

4. Click OK

Note (Windows): Virtual MIDI ports require loopMIDI. Create a port named mixxx-mcp before starting the server.

4. Run the MCP server

# stdio mode (Claude Desktop / claude-code)
python main.py

# HTTP mode (remote / multi-client)
python main.py --http --port 8080

5. Configure Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "mixxx": {
      "command": "python",
      "args": ["/path/to/mixxx-mcp/main.py"],
      "env": {}
    }
  }
}

Available Tools

OSC State

Mixxx broadcasts control changes via the JS script's engine.makeConnection() callbacks. The Python server listens on UDP 57121 at path /mixxx/<group>/<key>.

To fully enable OSC push (vs poll), the JS callbacks in mixxx-mcp.js need to forward values via a UDP socket. This requires a Mixxx build with liblo, or you can extend the JS script to use XMLHttpRequest to POST state to a local HTTP endpoint.

Mixxx Controls Reference

Full control list: https://manual.mixxx.org/latest/en/chapters/appendix/mixxx_controls.html

Key groups:

• [Channel1] – [Channel4] — Decks

• [Master] — Mixer master

• [Sampler1] – [Sampler64] — Samplers

• [EffectRack1_EffectUnit1] – [_EffectUnit4] — Effect units

• [EffectRack1_EffectUnit1_Effect1] – [_Effect3] — Individual effects

• [Playlist] — Library navigation

License

MIT