Servidor MCP de Rekordbox

Un servidor completo de Protocolo de Contexto de Modelo (MCP) para la gestión de bases de datos de rekordbox con acceso a la base de datos en tiempo real.

Construido usando pyrekordbox - Este proyecto no está afiliado al proyecto pyrekordbox ni a sus mantenedores.

Características

🗄️ Acceso a la base de datos

Conexión directa a la base de datos SQLite: Acceda a la base de datos cifrada de rekordbox directamente usando pyrekordbox
Consultas en tiempo real: Busque y filtre pistas con criterios exhaustivos
Operaciones de mutación seguras: Gestión de listas de reproducción con copias de seguridad automáticas y anotaciones de seguridad

🔍 Búsqueda y descubrimiento

Búsqueda avanzada: Búsqueda en múltiples campos a través de artista, título, género, tonalidad, BPM y más
Filtrado por tonalidad musical: Encuentre pistas en tonalidades compatibles para mezclas armónicas
Consultas de rango de BPM: Busque por rangos de tempo para el beatmatching
Filtros de valoración y recuento de reproducciones: Descubra sus pistas más queridas y más reproducidas

📊 Analítica e información

Estadísticas de la biblioteca: Estadísticas completas que incluyen distribución de géneros, BPM promedio, tiempo total de reproducción
Analítica de recuento de reproducciones: Rastree patrones y hábitos de escucha
Información de la colección: Comprenda la composición de su biblioteca musical
Acceso al historial de DJ: Acceso completo a su historial de sesiones de DJ y datos de rendimiento

⚙️ Operaciones de base de datos

Gestión de listas de reproducción: Cree, modifique y elimine listas de reproducción con protecciones de seguridad
Operaciones por lotes: Añada múltiples pistas a listas de reproducción de manera eficiente
Análisis de historial: Acceda al historial completo de sesiones de DJ y datos de rendimiento
Estadísticas de la biblioteca: Analítica e información exhaustiva

Related MCP server: MySQL Database Access

Arquitectura

Framework FastMCP: Servidor MCP de Python moderno usando FastMCP 2.0
Integración con pyrekordbox: Biblioteca madura para acceso a bases de datos cifradas
Consultas de base de datos en tiempo real: Operaciones directas de SQLite con soporte para SQLCipher
Listo para producción: Registro, manejo de errores y características de seguridad integradas

⚠️ Aviso de seguridad importante

HAGA UNA COPIA DE SEGURIDAD DE SU BIBLIOTECA DE REKORDBOX ANTES DE USAR

Este software accede directamente a su base de datos de rekordbox. Cree siempre una copia de seguridad de toda su biblioteca de rekordbox antes de usar esta herramienta como medida de precaución.

Requisitos de copia de seguridad

Debe crear una copia de seguridad completa de su biblioteca de rekordbox antes de usar este software. Consulte la documentación de rekordbox o los recursos de soporte para conocer los procedimientos de copia de seguridad adecuados para su configuración específica y versión de rekordbox.

Reconocimiento de riesgos

⚠️ Este proyecto accede directamente a su base de datos de rekordbox
⚠️ Úselo bajo su propia responsabilidad - no se ofrece garantía
⚠️ Pruebe exhaustivamente con copias de seguridad antes de usarlo en su biblioteca principal
⚠️ Los desarrolladores no son responsables de ninguna pérdida de datos o daño

Si no se siente cómodo con estos riesgos, utilice la funcionalidad de exportación XML de solo lectura en su lugar.

Inicio rápido

Requisitos previos

Python 3.12+
rekordbox 6 o 7 instalado con una biblioteca existente
COPIA DE SEGURIDAD COMPLETA de su biblioteca de rekordbox (vea el aviso de seguridad arriba)
Herramientas de solo lectura (búsqueda, estadísticas, historial) funcionan mientras rekordbox está abierto
Herramientas de escritura (crear lista de reproducción, añadir pistas, limpieza) requieren que rekordbox esté cerrado — pyrekordbox bloquea las confirmaciones cuando rekordbox está ejecutándose
Acceso a su base de datos de rekordbox (se admite la detección automática)

Instalación

# Install dependencies with uv
uv sync

# Run the server
uv run rekordbox-mcp

Configuración

El servidor admite tanto la detección automática de la base de datos como la configuración manual:

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

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

Configuración del cliente MCP

Añada a su configuración de Claude Desktop:

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

Herramientas disponibles (29 herramientas + 1 recurso)

Búsqueda y descubrimiento

search_tracks - Búsqueda avanzada de pistas en múltiples campos con filtrado (género, tonalidad, BPM, artista, título, valoración, etc.)
get_track_details - Obtenga metadatos completos para una pista específica por ID
get_tracks_by_key - Encuentre pistas en una tonalidad musical específica (ej. "5A", "12B")
get_tracks_by_bpm_range - Encuentre pistas dentro de un rango de BPM
get_genre_filepaths - Obtenga rutas de archivo para pistas que coincidan con un género (eficiente en tokens, devuelve solo rutas)
get_most_played_tracks - Obtenga pistas clasificadas por recuento de reproducciones
get_top_rated_tracks - Obtenga pistas clasificadas por valoración
get_unplayed_tracks - Obtenga pistas con cero recuento de reproducciones
get_track_file_path - Obtenga la ruta del sistema de archivos para una pista específica
search_tracks_by_filename - Busque pistas por coincidencia parcial de nombre de archivo

Analítica de la biblioteca

get_library_stats - Estadísticas completas de la biblioteca (recuento de pistas, tiempo de reproducción, BPM, géneros)
analyze_library - Agrupación y agregación personalizada (por género, tonalidad, año, artista o valoración)
validate_track_ids - Verifique una lista de IDs de pistas e informe cuáles son válidos/inválidos

Operaciones de listas de reproducción

get_playlists - Liste todas las listas de reproducción, incluidas las listas de reproducción inteligentes
get_playlist_tracks - Obtenga todas las pistas en una lista de reproducción específica
create_playlist - Cree una nueva lista de reproducción o carpeta ⚠️ (Mutación)
add_track_to_playlist - Añada una sola pista a una lista de reproducción ⚠️ (Mutación)
add_tracks_to_playlist - Añada múltiples pistas a una lista de reproducción en una sola operación ⚠️ (Mutación)
remove_track_from_playlist - Elimine una pista de una lista de reproducción ⚠️ (Mutación)
delete_playlist - Elimine una lista de reproducción permanentemente ⚠️ (Destructiva)

Historial y analítica de DJ

get_history_sessions - Obtenga todas las sesiones del historial de DJ con metadatos
get_session_tracks - Obtenga todas las pistas reproducidas en una sesión específica
get_recent_sessions - Obtenga sesiones dentro de un número especificado de días
search_history_sessions - Busque sesiones por nombre, año, mes o recuento mínimo de pistas
get_history_stats - Estadísticas completas de rendimiento de DJ e información

Limpieza de la biblioteca

find_broken_tracks - Escanee en busca de archivos faltantes, transmisiones de Apple Music, rutas vacías y referencias de listas de reproducción huérfanas
cleanup_orphaned_playlist_entries - Elimine entradas de listas de reproducción obsoletas que hacen referencia a pistas eliminadas ⚠️ (Mutación)
remove_broken_tracks - Elimine suavemente pistas por ID y elimínelas de todas las listas de reproducción ⚠️ (Destructiva)

Gestión de bases de datos

connect_database - Conéctese explícitamente con una ruta de base de datos personalizada opcional

Recursos

database-status - Estado actual de la conexión y estadísticas básicas

⚠️ Las operaciones de mutación modifican su base de datos de rekordbox y crean copias de seguridad automáticas ⚠️ Las operaciones destructivas eliminan datos permanentemente y requieren confirmación adicional

Ejemplos

Buscar pistas por tonalidad y BPM

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

Acceder al historial de DJ

# Get recent DJ sessions
get_recent_sessions(days=30)

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

Obtener información de la biblioteca

# Comprehensive library statistics
get_library_stats()

# DJ performance statistics
get_history_stats()

Gestión de listas de reproducción

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

Características de seguridad

Copias de seguridad automáticas: Todas las operaciones de mutación crean copias de seguridad automáticas de la base de datos antes de realizar cambios
Anotaciones de seguridad de FastMCP: Sugerencias de seguridad adecuadas para operaciones de mutación y destructivas
Protección de listas de reproducción inteligentes: Evita la eliminación de listas de reproducción inteligentes
Validación de conexión: Valida las conexiones y el acceso a la base de datos
Manejo de errores: Manejo integral de errores con registro detallado y reversión
Validación de entrada: Validación de entrada para todas las operaciones de base de datos
Seguridad en operaciones por lotes: Informes detallados sobre el éxito/fracaso de las operaciones por lotes

⚠️ Importante: Estas características de seguridad son protecciones complementarias. Mantenga siempre sus propias copias de seguridad y utilice este software bajo su propia responsabilidad.

Desarrollo

Estructura del proyecto

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

Ejecución de pruebas

uv run pytest

Calidad del código

# Format code
uv run black rekordbox_mcp/

# Lint code
uv run ruff rekordbox_mcp/

# Type checking
uv run mypy rekordbox_mcp/

Licencia

Licencia MIT

Descargo de responsabilidad

⚠️ ÚSELO BAJO SU PROPIA RESPONSABILIDAD ⚠️

Este proyecto no está afiliado a AlphaTheta (Pioneer DJ) ni al proyecto pyrekordbox
Este software accede directamente a su base de datos de rekordbox
No se proporciona garantía ni aval
Los desarrolladores no son responsables de ningún daño a su biblioteca de rekordbox
Usted asume todo el riesgo al usar este software

SIEMPRE haga una copia de seguridad de su biblioteca de rekordbox antes de usarlo. Pruebe exhaustivamente con copias de seguridad antes de usarlo en su biblioteca principal.

Al usar este software, usted reconoce que comprende estos riesgos y acepta usarlo bajo su propia responsabilidad.

rekordbox-mcp