rekordbox-mcp-main: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Is

An MCP server that provides Claude with direct read/write access to the rekordbox DJ software database. Built with FastMCP and pyrekordbox, it connects to rekordbox's encrypted SQLite (SQLCipher) database to expose 31 tools and 1 resource for searching tracks, importing new audio files, managing playlists, analyzing DJ history, and computing library statistics.

Commands

# Install dependencies
uv sync

# Run the MCP server
uv run rekordbox-mcp
uv run rekordbox-mcp --database-path /path/to/Pioneer  # custom path

# Code quality
uv run black rekordbox_mcp/    # format
uv run ruff rekordbox_mcp/     # lint
uv run mypy rekordbox_mcp/     # type check

# Run tests (90 tests, mocked pyrekordbox — no real database needed)
uv run pytest tests/ -v

Architecture

Three-layer design in rekordbox_mcp/:

• server.py -- FastMCP server. Defines all MCP tools as decorated async functions, manages a global RekordboxDatabase instance, handles signals (SIGINT/SIGTERM). Entry point is main(). Tools are grouped: search/discovery, playlist operations, track import, DJ history, library analytics, cleanup, and database management.

• database.py -- RekordboxDatabase class. Wraps pyrekordbox's Rekordbox6Database for encrypted SQLite access. Auto-detects the database path per platform (~/Library/Pioneer on macOS, ~/AppData/Roaming/Pioneer on Windows). Lazy connection on first tool call. All queries filter soft-deleted records (rb_local_deleted). Mutation methods auto-create timestamped backups (master_backup_YYYYMMDD_HHMMSS.db) before writes.

• models.py -- Pydantic models for Track, Playlist, HistorySession, HistoryTrack, SearchOptions, LibraryStats, HistoryStats. Validators handle date parsing and range constraints.

Connection flow: MCP client request -> server.py tool handler -> ensure_database_connected() -> RekordboxDatabase.connect() (first call only) -> pyrekordbox SQLCipher decryption -> query/mutate.