MCP-сервер для Rekordbox

Полнофункциональный сервер протокола Model Context Protocol (MCP) для управления базой данных rekordbox с доступом к данным в реальном времени.

Создано с использованием pyrekordbox — этот проект не связан с проектом pyrekordbox или его сопровождающими.

Возможности

🗄️ Доступ к базе данных

Прямое подключение к базе данных SQLite: Доступ к зашифрованной базе данных rekordbox напрямую через pyrekordbox
Запросы в реальном времени: Поиск и фильтрация треков по обширным критериям
Безопасные операции изменения: Управление плейлистами с автоматическим резервным копированием и аннотациями безопасности

🔍 Поиск и обнаружение

Расширенный поиск: Поиск по нескольким полям: исполнитель, название, жанр, тональность, BPM и другие
Фильтрация по музыкальной тональности: Поиск треков в совместимых тональностях для гармонического сведения
Запросы по диапазону BPM: Поиск по темпу для битмэтчинга
Фильтры по рейтингу и количеству воспроизведений: Находите свои самые любимые и часто проигрываемые треки

📊 Аналитика и инсайты

Статистика библиотеки: Полная статистика, включая распределение по жанрам, средний BPM, общую длительность воспроизведения
Аналитика воспроизведений: Отслеживание привычек и паттернов прослушивания
Инсайты коллекции: Понимание состава вашей музыкальной библиотеки
Доступ к истории DJ: Полный доступ к истории ваших сессий и данным о выступлениях

⚙️ Операции с базой данных

Управление плейлистами: Создание, изменение и удаление плейлистов с защитными механизмами
Пакетные операции: Эффективное добавление нескольких треков в плейлисты
Анализ истории: Доступ к полной истории сессий и данным о выступлениях
Статистика библиотеки: Комплексная аналитика и инсайты

Related MCP server: MySQL Database Access

Архитектура

Фреймворк FastMCP: Современный Python MCP-сервер на базе FastMCP 2.0
Интеграция с pyrekordbox: Зрелая библиотека для доступа к зашифрованным базам данных
Запросы к БД в реальном времени: Прямые операции SQLite с поддержкой SQLCipher
Готовность к продакшену: Встроенное логирование, обработка ошибок и функции безопасности

⚠️ Важное уведомление о безопасности

СОЗДАЙТЕ РЕЗЕРВНУЮ КОПИЮ БИБЛИОТЕКИ REKORDBOX ПЕРЕД ИСПОЛЬЗОВАНИЕМ

Это программное обеспечение напрямую обращается к вашей базе данных rekordbox. Всегда создавайте резервную копию всей библиотеки rekordbox перед использованием этого инструмента в качестве меры предосторожности.

Требования к резервному копированию

Вы должны создать полную резервную копию библиотеки rekordbox перед использованием этого ПО. Обратитесь к документации rekordbox или ресурсам поддержки для получения информации о правильных процедурах резервного копирования для вашей конкретной настройки и версии rekordbox.

Признание рисков

⚠️ Этот проект напрямую обращается к вашей базе данных rekordbox
⚠️ Используйте на свой страх и риск — гарантии не предоставляются
⚠️ Тщательно протестируйте с резервными копиями перед использованием на основной библиотеке
⚠️ Разработчики не несут ответственности за любую потерю данных или ущерб

Если вы не готовы к этим рискам, используйте вместо этого функцию экспорта в XML (только для чтения).

Быстрый старт

Предварительные требования

Python 3.12+
Установленный rekordbox 6 или 7 с существующей библиотекой
ПОЛНАЯ РЕЗЕРВНАЯ КОПИЯ библиотеки rekordbox (см. уведомление о безопасности выше)
Инструменты только для чтения (поиск, статистика, история) работают, пока rekordbox открыт
Инструменты записи (создание плейлиста, добавление треков, очистка) требуют, чтобы rekordbox был закрыт — pyrekordbox блокирует коммиты, когда rekordbox запущен
Доступ к базе данных rekordbox (поддерживается автоматическое обнаружение)

Установка

# Install dependencies with uv
uv sync

# Run the server
uv run rekordbox-mcp

Конфигурация

Сервер поддерживает как автоматическое обнаружение базы данных, так и ручную настройку:

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

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

Настройка MCP-клиента

Добавьте в конфигурацию Claude Desktop:

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

Доступные инструменты (29 инструментов + 1 ресурс)

Поиск и обнаружение

search_tracks - Расширенный поиск треков по нескольким полям с фильтрацией (жанр, тональность, BPM, исполнитель, название, рейтинг и т.д.)
get_track_details - Получение полных метаданных для конкретного трека по ID
get_tracks_by_key - Поиск треков в определенной музыкальной тональности (например, "5A", "12B")
get_tracks_by_bpm_range - Поиск треков в диапазоне BPM
get_genre_filepaths - Получение путей к файлам треков, соответствующих жанру (эффективно по токенам, возвращает только пути)
get_most_played_tracks - Получение треков, отсортированных по количеству воспроизведений
get_top_rated_tracks - Получение треков, отсортированных по рейтингу
get_unplayed_tracks - Получение треков с нулевым количеством воспроизведений
get_track_file_path - Получение пути к файлу для конкретного трека
search_tracks_by_filename - Поиск треков по частичному совпадению имени файла

Аналитика библиотеки

get_library_stats - Комплексная статистика библиотеки (количество треков, длительность, BPM, жанры)
analyze_library - Пользовательская группировка и агрегация (по жанру, тональности, году, исполнителю или рейтингу)
validate_track_ids - Проверка списка ID треков и отчет о том, какие из них действительны/недействительны

Операции с плейлистами

get_playlists - Список всех плейлистов, включая интеллектуальные плейлисты
get_playlist_tracks - Получение всех треков в конкретном плейлисте
create_playlist - Создание нового плейлиста или папки ⚠️ (Изменение)
add_track_to_playlist - Добавление одного трека в плейлист ⚠️ (Изменение)
add_tracks_to_playlist - Добавление нескольких треков в плейлист за одну операцию ⚠️ (Изменение)
remove_track_from_playlist - Удаление трека из плейлиста ⚠️ (Изменение)
delete_playlist - Удаление плейлиста навсегда ⚠️ (Деструктивно)

История DJ и аналитика

get_history_sessions - Получение всех сессий истории DJ с метаданными
get_session_tracks - Получение всех треков, сыгранных в конкретной сессии
get_recent_sessions - Получение сессий за указанное количество дней
search_history_sessions - Поиск сессий по имени, году, месяцу или минимальному количеству треков
get_history_stats - Комплексная статистика выступлений DJ и инсайты

Очистка библиотеки

find_broken_tracks - Сканирование на наличие отсутствующих файлов, потоков Apple Music, пустых путей и потерянных ссылок в плейлистах
cleanup_orphaned_playlist_entries - Удаление устаревших записей плейлистов, ссылающихся на удаленные треки ⚠️ (Изменение)
remove_broken_tracks - Мягкое удаление треков по ID и удаление из всех плейлистов ⚠️ (Деструктивно)

Управление базой данных

connect_database - Явное подключение с опциональным пользовательским путем к базе данных

Ресурсы

database-status - Текущий статус подключения и базовая статистика

⚠️ Операции изменения модифицируют вашу базу данных rekordbox и создают автоматические резервные копии ⚠️ Деструктивные операции безвозвратно удаляют данные и требуют дополнительного подтверждения

Примеры

Поиск треков по тональности и BPM

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

Доступ к истории DJ

# Get recent DJ sessions
get_recent_sessions(days=30)

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

Получение инсайтов библиотеки

# Comprehensive library statistics
get_library_stats()

# DJ performance statistics
get_history_stats()

Управление плейлистами

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

Функции безопасности

Автоматическое резервное копирование: Все операции изменения создают автоматические резервные копии базы данных перед внесением изменений
Аннотации безопасности FastMCP: Правильные подсказки безопасности для операций изменения и деструктивных операций
Защита интеллектуальных плейлистов: Предотвращает удаление интеллектуальных плейлистов
Проверка подключения: Проверяет подключения к базе данных и доступ
Обработка ошибок: Комплексная обработка ошибок с подробным логированием и откатом
Валидация ввода: Проверка ввода для всех операций с базой данных
Безопасность пакетных операций: Подробная отчетность об успехе/неудаче пакетных операций

⚠️ Важно: Эти функции безопасности являются дополнительной защитой. Всегда храните свои собственные резервные копии и используйте это программное обеспечение на свой страх и риск.

Разработка

Структура проекта

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

Запуск тестов

uv run pytest

Качество кода

# Format code
uv run black rekordbox_mcp/

# Lint code
uv run ruff rekordbox_mcp/

# Type checking
uv run mypy rekordbox_mcp/

Лицензия

Лицензия MIT

Отказ от ответственности

⚠️ ИСПОЛЬЗУЙТЕ НА СВОЙ СТРАХ И РИСК ⚠️

Этот проект не связан с AlphaTheta (Pioneer DJ) или проектом pyrekordbox
Это программное обеспечение напрямую обращается к вашей базе данных rekordbox
Никакие гарантии не предоставляются
Разработчики не несут ответственности за любой ущерб вашей библиотеке rekordbox
Вы принимаете на себя все риски при использовании этого программного обеспечения

ВСЕГДА делайте резервную копию библиотеки rekordbox перед использованием. Тщательно протестируйте с резервными копиями перед использованием на основной библиотеке.

Используя это программное обеспечение, вы подтверждаете, что понимаете эти риски и соглашаетесь использовать его под свою ответственность.

rekordbox-mcp