XDJ100SX/tools

XDJ-100SX Developer Tool

Claude Code MCP server + CLI + TUI for the XDJ-100SX Pi system. Push skin files, take screenshots, flash firmware, and manage the Pi — all from your editor.

---

Requirements

pip install paramiko watchdog textual

---

Quick start

python3 tools/xdj-pi-dev.py --check      # verify connection + environment
python3 tools/xdj-pi-dev.py --status     # live Pi + Mixxx status
python3 tools/xdj-pi-dev.py --ui         # interactive TUI
python3 tools/xdj-pi-dev.py --about      # authors & credits
python3 tools/xdj-pi-dev.py --help       # full command reference

---

Connection

The tool tries these in order:

1. --host flag
2. XDJ_HOST environment variable
3. XDJ100SX.local — mDNS, works on any network (WiFi or LAN)
4. 192.168.10.2 — static IP fallback for direct cable

Direct cable (no router)

One-time setup on your machine:

# macOS
sudo ifconfig en0 alias 192.168.10.1 255.255.255.0

# Linux
sudo ip addr add 192.168.10.1/24 dev eth0

# Windows (run as Administrator)
netsh interface ip set address "Ethernet" static 192.168.10.1 255.255.255.0

Then on the Pi (once):

python3 tools/xdj-pi-dev.py --setup-pi-dhcp

After that the Pi hands out IPs automatically — no manual config needed on any machine.

Multi-unit

Each Pi should have a unique hostname:

python3 tools/xdj-pi-dev.py --set-hostname xdj-unit2

Then from Claude Code:

• discover_units — lists all reachable XDJ units on the network
• select_unit — switches the active connection to a specific unit

---

Claude Code MCP setup

Add to .mcp.json in your project root:

{
  "mcpServers": {
    "xdj-pi-dev": {
      "command": "python3",
      "args": ["tools/xdj-pi-dev.py"]
    }
  }
}

Add to .claude/settings.local.json:

{
  "enabledMcpjsonServers": ["xdj-pi-dev"]
}

Restart Claude Code. Once connected, you can say things like:

• "push the skin and take a screenshot"
• "change the play button color in style.qss, push and screenshot"
• "restart Mixxx and navigate to the beat loop panel"
• "flash the firmware"
• "find all XDJ units on the network"

---

CLI reference

Setup

--check                  # preflight: deps, SSH, Mixxx, audio, Pico
--discover               # scan network for all Pi units
--setup-pi-dhcp          # configure Pi as DHCP server on eth0
--setup-ssh-keys         # passwordless SSH (recommended)
--set-hostname NAME      # rename Pi (e.g. xdj-unit2)
--backup-image           # backup SD card to .tar archive
--restore-ssh            # recovery guide if SSH is locked out

Skin development

--push                   # push all skin files to Pi
--push "*.qss"           # push only matching files
--pull                   # pull skin files from Pi to repo
--screenshot             # capture Pi display
--screenshot --panel ks  # navigate to panel first (hc/bl/bj/ks/st)
--restart                # restart Mixxx
--watch                  # watch, auto-push + screenshot on save
--watch --panel hc       # watch with panel navigation

MIDI

--push-midi              # push MIDI mapping to Pi
--pull-midi              # pull MIDI mapping from Pi
--midi-mon               # stream live MIDI messages (Ctrl-C to stop)

Pico firmware

--setup-pico-cli         # install arduino-cli on Pi (one-time)
--pico-compile           # compile firmware on Pi
--pico-bootloader        # reset Pico to UF2 bootloader
--pico-flash FILE.uf2    # flash a local .uf2 to Pi
--analyze                # live GPIO signal analyzer

Other

--cmd 'CMD'              # run arbitrary SSH command on Pi
--host 192.168.1.42      # target a specific IP or hostname
--ui                     # open interactive TUI (requires textual)
--about                  # show authors and credits

---

Skin development guide

See SKIN_DEV.md for Mixxx widget types, layout rules, ConfigKeys, QSS constraints, and color palette — everything Claude needs to build and modify skin files correctly.