Install

Prerequisites

• macOS on Apple Silicon — M1 or later
• Rekordbox 7.x installed with at least one collection imported
• Python 3.9 or newer for the automatic setup path
• An MCP host:
  • Claude Code — configured automatically at the ~/Music scope;
  • Claude Desktop — configured automatically when its installation is detected;
  • Codex — supported through the manual configuration below.

Tip

Use a capable current model for multi-step workflows. The first session is a much smaller connection check.

Install

Homebrew (recommended)

brew tap ryan-voitiskis/reklawdbox
brew install 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

Automatic setup

Homebrew

reklawdbox setup

Built from source

Run the binary you just built rather than assuming it is on your PATH:

./target/release/reklawdbox setup

The setup command first installs and validates the optional Essentia audio analysis environment. It then writes Claude Code configuration to ~/Music/.mcp.json and configures Claude Desktop when that app is detected.

Want to skip Essentia?

Essentia is not used by the first session. If Python, virtual-environment, or Essentia installation is unavailable—or you simply do not want it—skip the automatic setup command and use Manual configuration with the absolute path to the installed or source-built binary.

Reconnect your host

Configuration changes are picked up differently by each host:

• Claude Code: start it inside ~/Music, then run /mcp or start a new conversation.
• Claude Desktop: quit and reopen the app, then start a new conversation.
• Codex: after adding the server manually, start a new task.

For Claude Code, this starts the host in the same directory where automatic setup placed .mcp.json:

cd ~/Music && claude

Keep your host’s normal permission checks enabled. Depending on your host and settings, a multi-step workflow may ask you to approve tool calls or filesystem access. Grant only the reklawdbox tools and music-library paths that workflow needs. If your host supports scoped or remembered approvals, use those instead of disabling permission checks globally.

The Rekordbox database is opened read-only, but that does not make every operation read-only: tag and artwork tools can change audio files, while setup, caches, backups, and XML exports write other local files. Workflow approval checkpoints are procedural and do not replace host permissions. Read Safety & Trust before authorizing bulk file operations.

Verify the connection

Once the host has reconnected, continue to the dedicated first session. It uses one local, read-only library call and explains the expected result and its boundaries; there is no duplicate prompt to choose between here.

First 10 minutesConfirm the connection with one bounded, read-only result.

If tools are missing or the library cannot be opened, check Troubleshooting before continuing.

Discogs authorization

Discogs provides labels, catalog numbers, and release metadata for later enrichment and genre workflows. It is not used by the first session.

1. Ask the agent to look up a track on Discogs only when a later workflow needs it. On first use, you will receive an authorization URL to open in your browser.

2. After authorizing, future Discogs calls use that session automatically.

Manual configuration

Use this path when automatic setup does not support your host, when you want a different scope, or when you want to connect without installing Essentia.

Claude Code

Create a .mcp.json in the directory where you want the tools available:

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

If you built from source, replace the command with the absolute path to target/release/reklawdbox in your checkout.

Claude Desktop

Add the server to ~/Library/Application Support/Claude/claude_desktop_config.json:

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

If you built from source, use the absolute path to the source-built binary.

Codex

Homebrew install:

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

If you built from source, replace the final argument with the absolute path to target/release/reklawdbox in your checkout.

After changing configuration, follow the host-specific reconnect steps above, then continue to First 10 minutes.