Rekordbox MCP

🚀 Rekordbox MCP Server

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

This project is built using pyrekordbox, but it is not affiliated with the pyrekordbox project or its maintainers.

✨ Features

🗄️ Database Access

• Direct SQLite Database Connection: Leverage pyrekordbox to directly access the encrypted rekordbox database.
• Real-time Queries: Conduct searches and filters on tracks with comprehensive criteria.
• Safe Mutation Operations: Manage playlists with automatic backups and safety annotations.

🔍 Search & Discovery

• Advanced Search: Perform multi-field searches across artist, title, genre, key, BPM, and more.
• Musical Key Filtering: Locate 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: Obtain comprehensive stats including genre distribution, average BPM, and total playtime.
• Play Count Analytics: Track listening patterns and habits.
• Collection Insights: Understand the composition of your music library.
• DJ History Access: Gain full access to your DJ session history and performance data.

⚙️ Database Operations

• Playlist Management: Create, modify, and delete playlists with safety protections.
• Batch Operations: Efficiently add multiple tracks to playlists.
• History Analysis: Access complete DJ session history and performance data.
• Library Statistics: Get comprehensive analytics and insights.

🔧 Technical Details

• FastMCP Framework: Utilize the modern Python MCP server powered by FastMCP 2.0.
• pyrekordbox Integration: Rely on the mature library for encrypted database access.
• Real-time Database Queries: Conduct direct SQLite operations with SQLCipher support.
• Production Ready: Benefit from built-in logging, error handling, and safety features.

⚠️ Important Note

⚠️ Important Note

BACKUP YOUR REKORDBOX LIBRARY BEFORE USE. This software directly accesses your rekordbox database for analysis and querying. While currently read-only, 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
• A COMPLETE BACKUP of your rekordbox library (see safety notice above)
• rekordbox must be completely closed when using this tool
• 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"
    }
  }
}

💻 Usage Examples

Basic Usage

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()

Advanced Usage

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")

Available Tools

Search & Discovery

• search_tracks: Conduct advanced multi-field track searches with filtering (genre, key, BPM, artist, title, rating, etc.).
• get_library_stats: Obtain comprehensive library statistics and analytics.

Playlist Operations

• get_playlists: List all playlists, including smart playlists.
• get_playlist_tracks: Retrieve all tracks in a specific playlist.
• create_playlist: Create new playlists ⚠️ (Mutation).
• add_track_to_playlist: Add a single track to a playlist ⚠️ (Mutation).
• add_tracks_to_playlist: Add multiple tracks to a playlist in one operation ⚠️ (Mutation).
• remove_track_from_playlist: Remove a track from a playlist ⚠️ (Mutation).
• delete_playlist: Permanently delete a playlist ⚠️ (Destructive).

DJ History & Analytics

• get_recent_sessions: Access recent DJ session history and performance data.
• get_session_tracks: Get all tracks played in a specific session.
• get_history_stats: Obtain comprehensive DJ performance statistics and insights.

Resources

• database-status: Check the 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.

Safety Features

• Automatic Backups: All mutation operations create automatic database backups before changes.
• FastMCP Safety Annotations: Provide proper safety hints for mutation and destructive operations.
• Smart Playlist Protection: Prevent the deletion of intelligent playlists.
• Connection Validation: Validate database connections and access.
• Error Handling: Implement comprehensive error handling with detailed logging and rollback.
• Input Validation: Validate inputs for all database operations.
• Batch Operation Safety: Provide detailed reporting on the 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

This project is released under the MIT License.

Disclaimer

⚠️ Important Note

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.