MCP 服务器

rekordbox-mcp

A comprehensive MCP server for rekordbox database management with real-time database access, enabling track search, playlist operations, library analytics, and DJ history retrieval.

README

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

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.