Rekordbox MCP 서버

실시간 데이터베이스 액세스를 지원하는 rekordbox 데이터베이스 관리용 포괄적인 MCP(Model Context Protocol) 서버입니다.

pyrekordbox를 사용하여 구축됨 - 이 프로젝트는 pyrekordbox 프로젝트 또는 해당 관리자와 관련이 없습니다.

기능

🗄️ 데이터베이스 액세스

직접적인 SQLite 데이터베이스 연결: pyrekordbox를 사용하여 암호화된 rekordbox 데이터베이스에 직접 액세스
실시간 쿼리: 포괄적인 기준을 사용하여 트랙 검색 및 필터링
안전한 변경 작업: 자동 백업 및 안전 주석이 포함된 재생 목록 관리

🔍 검색 및 탐색

고급 검색: 아티스트, 제목, 장르, 키, BPM 등을 아우르는 다중 필드 검색
음악 키 필터링: 하모닉 믹싱을 위해 호환되는 키의 트랙 찾기
BPM 범위 쿼리: 비트매칭을 위한 템포 범위별 검색
평점 및 재생 횟수 필터: 가장 좋아하고 가장 많이 재생한 트랙 발견

📊 분석 및 통찰

라이브러리 통계: 장르 분포, 평균 BPM, 총 재생 시간을 포함한 포괄적인 통계
재생 횟수 분석: 트랙 청취 패턴 및 습관
컬렉션 통찰: 음악 라이브러리 구성 이해
DJ 기록 액세스: DJ 세션 기록 및 성능 데이터에 대한 전체 액세스

⚙️ 데이터베이스 작업

재생 목록 관리: 안전 보호 장치가 포함된 재생 목록 생성, 수정 및 삭제
일괄 작업: 여러 트랙을 재생 목록에 효율적으로 추가
기록 분석: 전체 DJ 세션 기록 및 성능 데이터 액세스
라이브러리 통계: 포괄적인 분석 및 통찰

Related MCP server: MySQL Database Access

아키텍처

FastMCP 프레임워크: FastMCP 2.0을 사용하는 최신 Python MCP 서버
pyrekordbox 통합: 암호화된 데이터베이스 액세스를 위한 성숙한 라이브러리
실시간 데이터베이스 쿼리: SQLCipher를 지원하는 직접적인 SQLite 작업
프로덕션 준비 완료: 내장 로깅, 오류 처리 및 안전 기능

⚠️ 중요 안전 공지

사용 전 REKORDBOX 라이브러리를 백업하십시오

이 소프트웨어는 rekordbox 데이터베이스에 직접 액세스합니다. 예방 조치로 이 도구를 사용하기 전에 전체 rekordbox 라이브러리의 백업을 항상 생성하십시오.

백업 요구 사항

이 소프트웨어를 사용하기 전에 rekordbox 라이브러리의 전체 백업을 생성해야 합니다. 특정 설정 및 rekordbox 버전에 대한 올바른 백업 절차는 rekordbox 설명서 또는 지원 리소스를 참조하십시오.

위험 고지

⚠️ 이 프로젝트는 rekordbox 데이터베이스에 직접 액세스합니다
⚠️ 사용자 책임 하에 사용하십시오 - 보증이 제공되지 않습니다
⚠️ 메인 라이브러리에서 사용하기 전에 백업으로 철저히 테스트하십시오
⚠️ 개발자는 데이터 손실이나 손상에 대해 책임을 지지 않습니다

이러한 위험이 불편하시다면 대신 읽기 전용 XML 내보내기 기능을 사용하십시오.

빠른 시작

사전 요구 사항

Python 3.12+
기존 라이브러리가 설치된 rekordbox 6 또는 7
rekordbox 라이브러리의 전체 백업 (위의 안전 공지 참조)
읽기 전용 도구(검색, 통계, 기록)는 rekordbox가 열려 있는 동안 작동합니다
쓰기 도구(재생 목록 생성, 트랙 추가, 정리)는 rekordbox가 닫혀 있어야 합니다 — rekordbox가 실행 중일 때 pyrekordbox는 커밋을 차단합니다
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 - 재생 횟수가 0인 트랙 가져오기
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