Getting Started

Prerequisites

• macOS on Apple Silicon (ARM64) — reklawdbox targets aarch64-apple-darwin
• Rekordbox 7.x installed with at least one collection imported

Install

Homebrew (recommended)

brew tap ryan-voitiskis/reklawdbox
brew install reklawdbox

The binary is installed to /opt/homebrew/bin/reklawdbox.

Build from source

Requires the Rust toolchain and Xcode Command Line Tools:

xcode-select --install  # if not already installed
git clone https://github.com/ryan-voitiskis/reklawdbox.git
cd reklawdbox
cargo build --release

The binary is at ./target/release/reklawdbox.

Setup

reklawdbox setup

This command does three things:

1. Installs Essentia — finds Python 3.9+, creates a managed venv at ~/.local/share/reklawdbox/essentia-venv, and installs Essentia via pip. Provides danceability, energy, loudness, and spectral features used by genre classification, set building, and audio analysis.

2. Configures Claude Code — writes ~/Music/.mcp.json so reklawdbox tools are available when you start Claude Code from your Music directory. Tools do not load in other projects.

3. Configures Claude Desktop — adds reklawdbox to the Claude Desktop config (loads globally, since Desktop has no project scoping).

Why ~/Music?

Reklawdbox tools are scoped to ~/Music to avoid polluting unrelated Claude Code sessions. When you start Claude Code from ~/Music, the tools load automatically. When you’re working in a code project, they stay out of the way. To add reklawdbox to other directories, see Adding to other directories.

Note

Essentia requires Python 3.9 or later. If you don’t have Python installed, get it from python.org or via brew install python.

Using with Claude Code

After running reklawdbox setup, start Claude Code from your Music directory:

cd ~/Music && claude

Reklawdbox tools load automatically because setup placed .mcp.json there. In any other directory, the tools stay out of the way.

Adding to other directories

To make reklawdbox available in additional directories, copy ~/Music/.mcp.json to the target directory:

cp ~/Music/.mcp.json /path/to/directory/

If you built from source, check that the command path inside the copied file points to your binary.

Or create a new .mcp.json there with the following content:

{
  "mcpServers": {
    "reklawdbox": {
      "command": "/opt/homebrew/bin/reklawdbox"
    }
  }
}

If you built from source, use the full absolute path to the binary (e.g., /Users/you/reklawdbox/target/release/reklawdbox).

Caution

If you previously registered reklawdbox at user scope (e.g., via claude mcp add), that entry in ~/.claude.json overrides any project .mcp.json. Remove it first: claude mcp remove -s user reklawdbox. See Troubleshooting.

Manual MCP host configuration

If reklawdbox setup already configured your MCP host, skip to Verify. Otherwise, configure manually:

Claude Code

Create ~/Music/.mcp.json:

{
  "mcpServers": {
    "reklawdbox": {
      "command": "/opt/homebrew/bin/reklawdbox"
    }
  }
}

If you built from source, use the full absolute path to the binary instead. Then start Claude Code from ~/Music:

cd ~/Music && claude

Claude Desktop

Add the following to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "reklawdbox": {
      "command": "/opt/homebrew/bin/reklawdbox"
    }
  }
}

If you built from source, use the full absolute path to the binary (e.g., /Users/you/reklawdbox/target/release/reklawdbox).

Codex

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

Tip

The Rekordbox database is auto-detected at ~/Library/Pioneer/rekordbox/master.db. Set REKORDBOX_DB_PATH only for non-standard locations.

Caution

After configuring your MCP host, reload it to pick up the changes. In Claude Code, run /mcp or start a new conversation. In Claude Desktop, quit and reopen the app.

Verify

Start a new conversation and paste this:

Show me a summary of my Rekordbox library.

It should return your track count, playlist count, and genre distribution. If it fails, check Troubleshooting.

Discogs authorization

Discogs enrichment provides labels, catalog numbers, and release metadata used by genre classification and library cleanup. The broker is preconfigured — no env vars or setup needed.

1. Call lookup_discogs for any track. On first use, the broker returns an OAuth URL — open it in your browser.

2. After authorizing, subsequent calls work automatically.

Next steps

Ask your agent: What workflows are available? — it will show a menu of step-by-step guides covering genre classification, set building, library cleanup, and more.

• Library Cleanup — recommended starting point for organizing a new collection
• Genre Classification — most common workflow
• Concepts — architecture and safety model