Skip to main content
Glama

Rekordbox MCP Server

A comprehensive Model Context Protocol (MCP) server for rekordbox database management with real-time database access.

Built using pyrekordbox - This project is not affiliated with the pyrekordbox project or its maintainers.

Features

đŸ—„ī¸ Database Access

  • Direct SQLite Database Connection: Access the encrypted rekordbox database directly using pyrekordbox

  • Real-time Queries: Search and filter tracks with comprehensive criteria

  • Safe Mutation Operations: Playlist management with automatic backups and safety annotations

🔍 Search & Discovery

  • Advanced Search: Multi-field search across artist, title, genre, key, BPM, and more

  • Musical Key Filtering: Find tracks in compatible keys for harmonic mixing

  • BPM Range Queries: Search by tempo ranges for beatmatching

  • Rating and Play Count Filters: Discover your most loved and most played tracks

📊 Analytics & Insights

  • Library Statistics: Comprehensive stats including genre distribution, average BPM, total playtime

  • Play Count Analytics: Track listening patterns and habits

  • Collection Insights: Understand your music library composition

  • DJ History Access: Full access to your DJ session history and performance data

âš™ī¸ Database Operations

  • Playlist Management: Create, modify, and delete playlists with safety protections

  • Batch Operations: Add multiple tracks to playlists efficiently

  • History Analysis: Access complete DJ session history and performance data

  • Library Statistics: Comprehensive analytics and insights

Related MCP server: Tempo

Architecture

  • FastMCP Framework: Modern Python MCP server using FastMCP 2.0

  • pyrekordbox Integration: Mature library for encrypted database access

  • Real-time Database Queries: Direct SQLite operations with SQLCipher support

  • Production Ready: Built-in logging, error handling, and safety features

âš ī¸ Important Safety Notice

BACKUP YOUR REKORDBOX LIBRARY BEFORE USE

This software directly accesses your rekordbox database. Always create a backup of your entire rekordbox library before using this tool as a precautionary measure.

Backup Requirements

You should create a complete backup of your rekordbox library before using this software. Consult rekordbox documentation or support resources for proper backup procedures for your specific setup and rekordbox version.

Risk Acknowledgment

  • âš ī¸ This project accesses your rekordbox database directly

  • âš ī¸ Use at your own risk - no warranty provided

  • âš ī¸ Test thoroughly with backups before using on your main library

  • âš ī¸ The developers are not responsible for any data loss or damage

If you are not comfortable with these risks, use the read-only XML export functionality instead.

Quick Start

Prerequisites

  • Python 3.12+

  • rekordbox 6 or 7 installed with an existing library

  • COMPLETE BACKUP of your rekordbox library (see safety notice above)

  • Read-only tools (search, stats, history) work while rekordbox is open

  • Write tools (create playlist, add tracks, cleanup) require rekordbox to be closed — pyrekordbox blocks commits when rekordbox is running

  • Access to your rekordbox database (automatic detection supported)

Installation

# Install dependencies with uv
uv sync

# Run the server
uv run rekordbox-mcp

Configuration

The server supports both automatic database detection and manual configuration:

# Auto-detect rekordbox database (recommended)
uv run rekordbox-mcp

# Specify custom database path
uv run rekordbox-mcp --database-path /path/to/rekordbox/Pioneer

MCP Client Setup

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "rekordbox-database": {
      "command": "uv",
      "args": ["run", "rekordbox-mcp"],
      "cwd": "/path/to/rekordbox-mcp"
    }
  }
}

Available Tools (31 tools + 1 resource)

Search & Discovery

  • search_tracks - Advanced multi-field track search with filtering (genre, key, BPM, artist, title, rating, etc.)

  • get_track_details - Get full metadata for a specific track by ID

  • get_tracks_by_key - Find tracks in a specific musical key (e.g., "5A", "12B")

  • get_tracks_by_bpm_range - Find tracks within a BPM range

  • get_genre_filepaths - Get filepaths for tracks matching a genre (token-efficient, returns only paths)

  • get_most_played_tracks - Get tracks ranked by play count

  • get_top_rated_tracks - Get tracks ranked by rating

  • get_unplayed_tracks - Get tracks with zero play count

  • get_track_file_path - Get the file system path for a specific track

  • search_tracks_by_filename - Search tracks by partial filename match

Library Analytics

  • get_library_stats - Comprehensive library statistics (track count, playtime, BPM, genres)

  • analyze_library - Custom grouping and aggregation (by genre, key, year, artist, or rating)

  • validate_track_ids - Verify a list of track IDs and report which are valid/invalid

Playlist Operations

  • get_playlists - List all playlists including smart playlists

  • get_playlist_tracks - Get all tracks in a specific playlist

  • create_playlist - Create new playlist or folder âš ī¸ (Mutation)

  • add_track_to_playlist - Add single track to playlist âš ī¸ (Mutation)

  • add_tracks_to_playlist - Add multiple tracks to playlist in one operation âš ī¸ (Mutation)

  • remove_track_from_playlist - Remove track from playlist âš ī¸ (Mutation)

  • delete_playlist - Delete playlist permanently âš ī¸ (Destructive)

DJ History & Analytics

  • get_history_sessions - Get all DJ history sessions with metadata

  • get_session_tracks - Get all tracks played in a specific session

  • get_recent_sessions - Get sessions within a specified number of days

  • search_history_sessions - Search sessions by name, year, month, or minimum track count

  • get_history_stats - Comprehensive DJ performance statistics and insights

Track Import

  • import_track - Import a single audio file into the library; reads ID3 tags via mutagen by default, accepts metadata overrides âš ī¸ (Mutation)

  • import_tracks - Batch-import files and/or directories (recursive, extension filter); returns track IDs for follow-up playlist actions âš ī¸ (Mutation)

â„šī¸ Imported tracks are unanalyzed — waveforms, beatgrids, and hot cues are generated by rekordbox itself. After import, open rekordbox and run Analyze Tracks on the new imports. Supported formats: mp3, m4a, flac, wav, aiff.

Library Cleanup

  • find_broken_tracks - Scan for missing files, Apple Music streams, empty paths, and orphaned playlist refs

  • cleanup_orphaned_playlist_entries - Remove stale playlist entries referencing deleted tracks âš ī¸ (Mutation)

  • remove_broken_tracks - Soft-delete tracks by ID and remove from all playlists âš ī¸ (Destructive)

Database Management

  • connect_database - Explicitly connect with optional custom database path

Resources

  • database-status - Current connection status and basic stats

âš ī¸ Mutation operations modify your rekordbox database and create automatic backups
âš ī¸ Destructive operations permanently delete data and require extra confirmation

Examples

Search for tracks by key and BPM

# Find tracks in 5A key with BPM between 120-130
search_tracks(key="5A", bpm_min=120, bpm_max=130, limit=20)

Access DJ History

# Get recent DJ sessions
get_recent_sessions(days=30)

# Get tracks from a specific session
get_session_tracks(session_id="12345")

Get library insights

# Comprehensive library statistics
get_library_stats()

# DJ performance statistics
get_history_stats()

Playlist Management

# Create a new playlist
create_playlist(name="Hidden Bangers", parent_id="root")

# Add single track to playlist
add_track_to_playlist(playlist_id="136766232", track_id="218048716")

# Add multiple tracks efficiently (recommended for batch operations)
add_tracks_to_playlist(
    playlist_id="136766232", 
    track_ids=["218048716", "253968855", "148359536", "76341043"]
)

# Remove track from playlist
remove_track_from_playlist(playlist_id="136766232", track_id="218048716")

# Delete playlist (with safety confirmation)
delete_playlist(playlist_id="136766232")

Importing New Tracks

# Import a single file — auto-reads ID3 tags, allows overrides
import_track(
    path="/Users/me/Downloads/new_banger.mp3",
    rating=5,
    genre="Deep House",
)

# Batch-import a directory (recursive by default) and stage for analysis
result = import_tracks(
    paths=["/Users/me/Auditioned/March"],
    recursive=True,
    auto_tag=True,
)

# Park imports in a playlist so they're easy to find in rekordbox
create_playlist(name="Unanalyzed Imports")
add_tracks_to_playlist(
    playlist_id="<id from above>",
    track_ids=[t["track_id"] for t in result["imported"]],
)
# Then open rekordbox and run Analyze Tracks on that playlist.

Safety Features

  • Automatic Backups: All mutation operations create automatic database backups before changes

  • FastMCP Safety Annotations: Proper safety hints for mutation and destructive operations

  • Smart Playlist Protection: Prevents deletion of intelligent playlists

  • Connection Validation: Validates database connections and access

  • Error Handling: Comprehensive error handling with detailed logging and rollback

  • Input Validation: Input validation for all database operations

  • Batch Operation Safety: Detailed reporting on success/failure of batch operations

âš ī¸ Important: These safety features are supplementary protections. Always maintain your own backups and use this software at your own risk.

Development

Project Structure

rekordbox_mcp/
   __init__.py          # Package initialization
   server.py            # FastMCP server and tool definitions
   database.py          # Database connection and operations
   models.py            # Pydantic data models

Running Tests

uv run pytest

Code Quality

# Format code
uv run black rekordbox_mcp/

# Lint code
uv run ruff rekordbox_mcp/

# Type checking
uv run mypy rekordbox_mcp/

License

MIT License

Disclaimer

âš ī¸ USE AT YOUR OWN RISK âš ī¸

  • This project is not affiliated with AlphaTheta (Pioneer DJ) or the pyrekordbox project

  • This software directly accesses your rekordbox database

  • No warranty or guarantee is provided

  • The developers are not responsible for any damage to your rekordbox library

  • You assume all risk when using this software

ALWAYS backup your rekordbox library before use. Test thoroughly with backup copies before using on your main library.

By using this software, you acknowledge that you understand these risks and agree to use it at your own responsibility.

Available Tools

31 tools
add_tracks_to_playlistA
Idempotent

Add multiple tracks to an existing playlist in one operation.

âš ī¸ CAUTION: This modifies your rekordbox database!

Args: playlist_id: ID of the playlist to modify track_ids: List of track IDs to add

Returns: Detailed results of the batch operation

Inputs: track_ids (required), playlist_id (required). Returns: object

add_track_to_playlistB
Idempotent

Add a track to an existing playlist.

âš ī¸ CAUTION: This modifies your rekordbox database!

Args: playlist_id: ID of the playlist to modify track_id: ID of the track to add

Returns: Result of the operation

Inputs: track_id (required), playlist_id (required). Returns: object

analyze_libraryB

Analyze library with grouping and aggregation.

Args: group_by: Field to group by (genre, key, year, artist, rating) aggregate_by: Aggregation method (count, playCount, totalTime) top_n: Number of top results to return

Returns: Analysis results

Inputs: top_n, group_by, aggregate_by. Returns: object

cleanup_orphaned_playlist_entriesA
Idempotent

Remove orphaned playlist entries that reference deleted tracks.

These orphaned entries cause blank '[1] The file doesn't exist' errors when exporting to USB. This tool removes the stale PlaylistSong rows while preserving all active tracks and playlists.

âš ī¸ CAUTION: This modifies your rekordbox database! A backup is created automatically.

Returns: Count and details of removed orphaned entries

Inputs: no named parameters. Returns: object

connect_databaseA

Connect to the rekordbox database.

Args: database_path: Optional path to database directory. If not provided, auto-detection is used.

Returns: Connection status message

Inputs: database_path. Returns: object

create_playlistA

Create a new playlist or folder in rekordbox.

âš ī¸ CAUTION: This modifies your rekordbox database!

Args: name: Name for the new playlist or folder parent_id: Optional parent folder ID (omit for root level) is_folder: If True, create as a folder that can contain other playlists

Returns: Information about the created playlist or folder

Inputs: name (required), is_folder, parent_id. Returns: object

delete_playlistA
DestructiveIdempotent

Delete a playlist from rekordbox.

âš ī¸ DANGER: This permanently deletes a playlist and cannot be undone!

Args: playlist_id: ID of the playlist to delete

Returns: Result of the operation

Inputs: playlist_id (required). Returns: object

find_broken_tracksA

Scan the library for broken tracks and orphaned playlist references.

Detects:

  • Tracks with empty file paths

  • Apple Music streaming references (can't export to USB/CDJ)

  • Tracks pointing to files that no longer exist on disk

  • Orphaned playlist entries referencing deleted tracks (causes blank USB export errors)

Returns: Report with broken tracks grouped by category and a summary with counts

Inputs: no named parameters. Returns: object

get_genre_filepathsA

Get filepaths for all tracks matching a genre.

This tool is optimized for token efficiency - returns only filepaths. Useful for creating export scripts for selective library exports.

Args: genre: Genre term to search for (case-insensitive substring match)

Returns: List of absolute filepaths for matching tracks

Inputs: genre (required). Returns: result

get_history_sessionsA

Get DJ history sessions from rekordbox.

Args: include_folders: Whether to include folder entries (years/months) limit: Maximum number of sessions to return

Returns: List of history sessions with metadata

Inputs: limit, include_folders. Returns: result

get_history_statsB

Get comprehensive statistics about DJ history sessions.

Returns: Statistics about all history sessions including totals and trends

Inputs: no named parameters. Returns: object

get_library_statsC

Get comprehensive library statistics.

Returns: Dictionary containing various library statistics

Inputs: no named parameters. Returns: object

get_most_played_tracksA

Get the most played tracks in the library.

Args: limit: Maximum number of tracks to return

Returns: List of most played tracks

Inputs: limit. Returns: result

get_playlistsA

Get all playlists from the rekordbox database.

Returns: List of playlists with metadata

Inputs: no named parameters. Returns: result

get_playlist_tracksA

Get all tracks in a specific playlist.

Args: playlist_id: The unique playlist identifier

Returns: List of tracks in the playlist

Inputs: playlist_id (required). Returns: result

get_recent_sessionsB

Get recent DJ history sessions within the specified number of days.

Args: days: Number of days to look back (default: 30)

Returns: List of recent history sessions

Inputs: days. Returns: result

get_session_tracksA

Get all tracks from a specific DJ history session.

Args: session_id: The session's unique identifier

Returns: List of tracks in the session with performance context

Inputs: session_id (required). Returns: result

get_top_rated_tracksA

Get the highest rated tracks in the library.

Args: limit: Maximum number of tracks to return

Returns: List of top rated tracks

Inputs: limit. Returns: result

get_track_detailsA

Get detailed information about a specific track.

Args: track_id: The unique track identifier

Returns: Detailed track information including metadata, cue points, and play history

Inputs: track_id (required). Returns: object

get_track_file_pathB

Get the file system path for a specific track.

Args: track_id: The unique track identifier

Returns: Dictionary containing file path information

Inputs: track_id (required). Returns: object

get_tracks_by_bpm_rangeA

Get tracks within a specific BPM range.

Args: bpm_min: Minimum BPM bpm_max: Maximum BPM

Returns: List of tracks within the BPM range

Inputs: bpm_max (required), bpm_min (required). Returns: result

get_tracks_by_keyA

Get all tracks in a specific musical key.

Args: key: Musical key (e.g., "5A", "12B")

Returns: List of tracks in the specified key

Inputs: key (required). Returns: result

get_unplayed_tracksA

Get tracks that have never been played.

Args: limit: Maximum number of tracks to return

Returns: List of unplayed tracks

Inputs: limit. Returns: result

import_trackA

Import a single audio file into the rekordbox library.

âš ī¸ CAUTION: This modifies your rekordbox database — rekordbox must be closed.

The track is added as unanalyzed; open rekordbox and run "Analyze Tracks" to generate waveforms, beatgrids, and hot cues.

Args: path: Absolute path to the audio file (mp3/m4a/flac/wav/aiff) title: Override the title (defaults to ID3 tag if auto_tag=True) artist: Override the artist (creates artist row if new) album: Override the album genre: Override the genre label: Override the record label bpm: Override the BPM (float, e.g. 128.0) rating: Override the rating (0–5) comments: Track comments year: Release year auto_tag: Read ID3 tags via mutagen and prefill metadata (default True). Explicit arguments always win over tag values.

Returns: Result with status (success/skipped/error), track_id, and resolved metadata.

Inputs: path (required), bpm, year, album, +7 more. Returns: object

import_tracksA

Batch-import audio files and/or directories into the rekordbox library.

âš ī¸ CAUTION: This modifies your rekordbox database — rekordbox must be closed.

Tracks are added as unanalyzed. Open rekordbox afterwards and run "Analyze Tracks" on the new imports to generate waveforms/beatgrids/hot cues. Tip: follow up with add_tracks_to_playlist using the returned track_ids to stage them for easy selection in rekordbox.

Args: paths: List of file paths and/or directory paths. recursive: If a directory is given, descend into subdirectories (default True). auto_tag: Read ID3 tags via mutagen for each file (default True). extensions: Restrict directory scans to these extensions (e.g. ["mp3", "flac"]). Defaults to all supported types.

Returns: Summary with counts and per-file details for imported / skipped / failed.

Inputs: paths (required), auto_tag, recursive, extensions. Returns: object

remove_broken_tracksA
DestructiveIdempotent

Soft-delete tracks by ID and remove them from all playlists.

Use find_broken_tracks first to identify which tracks to remove. Tracks are soft-deleted (marked as deleted in the database, not permanently erased).

âš ī¸ DANGER: This removes tracks from your rekordbox library!

Args: track_ids: List of track IDs to remove

Returns: Details of removed tracks and any IDs that were not found

Inputs: track_ids (required). Returns: object

remove_track_from_playlistA
Idempotent

Remove a track from a playlist.

âš ī¸ CAUTION: This modifies your rekordbox database!

Args: playlist_id: ID of the playlist to modify track_id: ID of the track to remove

Returns: Result of the operation

Inputs: track_id (required), playlist_id (required). Returns: object

search_history_sessionsA

Search DJ history sessions with various filters.

Args: query: Search query for session names year: Filter by year (e.g., "2025") month: Filter by month (e.g., "08" for August) min_tracks: Minimum number of tracks in session limit: Maximum number of results

Returns: List of matching history sessions

Inputs: year, limit, month, query, +1 more. Returns: result

search_tracksB

Search tracks in the rekordbox database.

Args: query: General search query (searches across multiple fields) artist: Filter by artist name title: Filter by track title genre: Filter by genre key: Filter by musical key (e.g., "5A", "12B") bpm_min: Minimum BPM bpm_max: Maximum BPM rating_min: Minimum rating (0-5) limit: Maximum number of results to return

Returns: List of matching tracks with metadata

Inputs: key, genre, limit, query, +5 more. Returns: result

search_tracks_by_filenameA

Search for tracks by filename.

Args: filename: Filename to search for (partial match)

Returns: List of tracks matching the filename

Inputs: filename (required). Returns: result

validate_track_idsB

Validate a list of track IDs and show which are valid/invalid.

Args: track_ids: List of track IDs to validate

Returns: Validation results with valid and invalid IDs

Inputs: track_ids (required). Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelogâ€Ļ

    TDQS

    A3.5/5.0

    Scored across 31 tools

    Disambiguation4/5

    Most tools target distinct resource-action pairs, but there is some overlap between general search_tracks and specialized filters like get_tracks_by_key or search_tracks_by_filename. Single vs batch variants are clearly distinguished by singular/plural naming.

    Naming Consistency5/5

    Tool names follow a consistent verb_noun pattern (get_, search_, create_, delete_, add_, remove_, import_, etc.). Singular and plural forms clearly differentiate single-item and batch operations.

    Tool Count2/5

    With 31 tools, the server exceeds the typical 3-15 range and even the 25-tool threshold. While the scope covers tracks, playlists, history, and maintenance, the sheer number may be overwhelming for agents.

    Completeness3/5

    Core track and playlist workflows are covered (import, search, create, add/remove), but there are notable gaps: no update track metadata, no rename playlist, and no general delete track (only broken tracks). History session coverage is thorough.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      MCP server for rekordbox DJ database access. Provides read-only querying of tracks, playlists, and DJ session history from encrypted rekordbox SQLite databases using pyrekordbox.
      25
      135
      Python
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server for Spotify control and synchronized lyrics retrieval that enables playback management, queue navigation, and music search capabilities. It also features perception tools for real-time track analysis, including BPM, key detection, and timestamped lyrics.
      3
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that provides access to the Beatport API for music discovery and data retrieval, enabling users to search for tracks, artists, labels, releases, and charts through natural language.
      4
      MIT