reklawdbox

AI-assisted Rekordbox 7 library management for Apple Silicon Macs.

reklawdbox connects an MCP-capable AI host to your local Rekordbox library, so you can inspect, clean, classify, and organize tracks through conversation. It combines library data, online metadata, and audio evidence while keeping normal Rekordbox metadata changes reviewable: the MCP server never performs SQL writes to master.db; it stages changes in memory and exports XML for you to import.

Some explicit workflows can write audio tags, artwork, or other files. The safety model below explains each boundary, including the separate backup-restore command.

Documentation · Install guide · Workflow catalog · Tool reference

Why use it?

Maintaining a DJ library involves repetitive work across Rekordbox, audio files, metadata sites, and listening notes. reklawdbox gives your AI host purpose-built tools for that work while you choose the scope, review proposed changes, and control what reaches Rekordbox.

You can use it to:

• understand your library, playlists, play history, and health;
• fill missing labels, years, albums, and genres;
• compare Discogs, MusicBrainz, Bandcamp, label, and audio evidence;
• find compatible tracks already in your library and build ordered sets;
• prepare new downloads, tags, and artwork before Rekordbox import; and
• export approved metadata changes and playlists as Rekordbox XML.

Quick start

Requirements

• macOS 15 or newer on Apple Silicon (M1 or later) for managed Essentia setup
• Rekordbox 7.x with at least one collection imported
• An MCP host for conversational use: Claude Code, Claude Desktop, the ChatGPT desktop app, Codex CLI, or the Codex IDE extension
• CPython 3.14 for reklawdbox setup and creating or refreshing Essentia evidence

Python is not required for the built-in Stratum analysis or a manual MCP configuration without Essentia.

Install and connect

brew tap ryan-voitiskis/reklawdbox
brew install reklawdbox
reklawdbox setup

With no valid expert override, setup installs and validates the managed Essentia analysis backend at the stable path ~/.local/share/reklawdbox/essentia-venv/bin/python. It uses the wheel-only runtime manifest Essentia 2.1b6.dev1438, NumPy 2.5.1, PyYAML 6.0.3, and six 1.17.0; internal immutable generations are not a user-facing path. Essentia is an externally installed AGPL-3.0-only package and is not bundled with Reklawdbox. The core server, library/export tools, Stratum analysis, transition scoring, and pool scoring work without Python. Fresh, valid cached Stratum and Essentia evidence is required for Full classification and profile calibration. Those cache-only operations do not require a live Python process once current rows exist; Python is needed to create or refresh the Essentia row. Without both current rows, classification is Degraded: confidence is capped at Low, review is required, and the result is never auto-staged.

Standard use needs no environment variable. A valid CRATE_DIG_ESSENTIA_PYTHON remains an expert override and is reused only when it matches the same complete runtime manifest.

setup also configures Claude Code at ~/Music/.mcp.json, configures Claude Desktop when detected, and checks the Rekordbox database connection. Then reconnect your host:

• Claude Code: start it from ~/Music, then run /mcp or start a new conversation.

• Claude Desktop: quit and reopen the app.

• OpenAI clients: the ChatGPT desktop app, Codex CLI, and Codex IDE extension share MCP configuration. Add the server once in the ChatGPT desktop app under Settings → MCP servers, or from Codex CLI:

  codex mcp add reklawdbox -- /opt/homebrew/bin/reklawdbox
  

  Then restart the desktop app or IDE extension, or start a new Codex CLI session. Use /mcp to confirm that the server is connected.

If you built from source, run ./target/release/reklawdbox setup and use that binary's absolute path in your host configuration. To use reklawdbox without Essentia, skip setup and follow the manual configuration guide; classification will remain Degraded and cannot auto-stage until both analyzer caches are current.

Verify with one read-only request

Paste this into your connected MCP host:

Use only reklawdbox's read_library tool. Show me:
- my total track and playlist counts
- my top genres
- my average BPM and key distribution

Do not call any other tool, use online services, analyze or modify audio files,
create or update caches, stage changes, create backups, or export XML. If
read_library is unavailable or fails, stop and tell me the error.

If you see your library summary, the connection works and nothing was changed. Continue with the first-session guide or choose a goal below.

Choose a goal

For release-embedded, step-by-step SOPs, ask your agent to call help() without a topic. The public workflow catalog also includes composite and planning guides that are not separate runtime help entries.

Safety model

Read-only Rekordbox access does not mean every operation is read-only. Know which layer a workflow uses:

Staged changes disappear when the MCP process ends unless exported. A failed backup or XML write restores the in-memory snapshot for retry; a successful export clears the exported snapshot.

Keep your MCP host's normal permission checks enabled. Workflow approval steps are guidance for the agent, not a universal runtime confirmation layer for direct file tools.

See Safety & Trust and XML Export for the full operating model and current Rekordbox import steps.

How it works

flowchart LR
    host["MCP host<br/>Claude Code · Claude Desktop<br/>ChatGPT desktop app · Codex CLI/IDE"] <-->|"MCP over stdio"| app["reklawdbox"]

    app -->|"read-only SQL"| db[("Rekordbox master.db")]
    app --> providers["Discogs · MusicBrainz<br/>Bandcamp"]
    app --> analysis["Stratum + capability-specific Essentia"]
    providers --> state[("Local state")]
    analysis --> state

    app --> staged["In-memory changes"]
    staged --> export["Backup + XML export"]
    export -->|"manual import"| rekordbox["Rekordbox"]

    app -->|"explicit file tools"| files["Audio and artwork files"]

• Audio analysis: the built-in stratum-dsp backend provides tempo/key confidence, beat-grid, rhythm, decay, and structure evidence. Essentia adds loudness, danceability, onset, timbral, and spectral evidence. It is optional for startup and unrelated workflows, but required alongside fresh Stratum evidence for Full classification and calibration. Transition and pool scoring continue to exclude unavailable axes or use their existing BPM-based energy proxy.
• Enrichment: Discogs access goes through the open-source broker, which handles OAuth, rate limiting, and response caching without putting Discogs consumer secrets in the Rust binary. Other providers are queried directly for specific metadata evidence. Library search, classification, scoring, and audio analysis stay local; an uncached provider lookup sends identifying track metadata to that selected service and caches the result locally.
• Workflow guidance: the site and each released binary share the same SOP partials. Each release therefore carries the workflow text built with it.

Read the architecture guide for cache freshness, scoring, provider, and data-flow details.

CLI

Most DJ workflows happen through the connected AI host. MCP hosts launch the binary over piped stdin; in an interactive terminal, use CLI subcommands for setup, bulk processing, backups, and direct file work.

Run reklawdbox <subcommand> --help or see the CLI reference for flags, defaults, and examples.

Build and develop

Build from source with the Rust toolchain and Xcode Command Line Tools:

git clone https://github.com/ryan-voitiskis/reklawdbox.git
cd reklawdbox
cargo build --release
./target/release/reklawdbox --version

The full local verification path is:

cargo fmt --check
dprint check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace --no-fail-fast
cargo build --release
./target/release/reklawdbox --version
./target/release/reklawdbox --help
node scripts/mcp-smoke.mjs --bin ./target/release/reklawdbox --skip-db

The repository contains the root Rust MCP/CLI crate, the stratum-dsp/ workspace crate, the Astro documentation site in site/, and the Cloudflare Discogs broker in broker/. See src/README.md for the code map and CONTRIBUTING.md for contribution expectations.

Releasing

Maintainers pass a new semantic version to scripts/release.sh from a clean main. The script runs the release preflight, uses a DB-backed MCP smoke test by default, bumps and commits version files, tags the commit, and pushes main plus the tag. Set REKLAWDBOX_RELEASE_SKIP_DB_SMOKE=1 only when the DB-free smoke is required. Tag CI publishes the Apple Silicon GitHub release and updates the Homebrew tap.

License

MIT