Skip to main content
Glama
rekordbox-mcp

rekordbox-mcp

Rekordbox MCP 服务器

一个用于 rekordbox 数据库管理的综合模型上下文协议 (MCP) 服务器,支持实时数据库访问。

基于 pyrekordbox 构建 - 本项目与 pyrekordbox 项目及其维护者无关。

功能特性

🗄️ 数据库访问

  • 直接 SQLite 数据库连接:使用 pyrekordbox 直接访问加密的 rekordbox 数据库

  • 实时查询:使用综合条件搜索和筛选曲目

  • 安全变更操作:带有自动备份和安全注释的播放列表管理

🔍 搜索与发现

  • 高级搜索:跨艺术家、标题、流派、调性、BPM 等的多字段搜索

  • 调性筛选:查找用于谐波混音的兼容调性曲目

  • BPM 范围查询:按速度范围搜索以进行节拍匹配

  • 评分和播放次数筛选:发现您最喜爱和播放次数最多的曲目

📊 分析与洞察

  • 库统计:综合统计数据,包括流派分布、平均 BPM、总播放时长

  • 播放次数分析:追踪收听模式和习惯

  • 收藏洞察:了解您的音乐库构成

  • DJ 历史访问:完全访问您的 DJ 会话历史和表演数据

⚙️ 数据库操作

  • 播放列表管理:创建、修改和删除播放列表,并提供安全保护

  • 批量操作:高效地将多首曲目添加到播放列表

  • 历史分析:访问完整的 DJ 会话历史和表演数据

  • 库统计:综合分析与洞察

Related MCP server: AbletonMCP

架构

  • 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 - 获取播放次数为零的曲目

  • 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 库。在主库上使用前,请先用备份副本进行彻底测试。

使用本软件即表示您了解这些风险,并同意自行承担责任。

Available Tools

25 tools
add_tracks_to_playlistA
Idempotent

Add multiple tracks to an existing playlist in one operation.

⚠️ CAUTION: This modifies your rekordbox database!

Args: playlist_id: ID of the playlist to modify track_ids: List of track IDs to add

Returns: Detailed results of the batch operation

Inputs: playlist_id (required), track_ids (required). Returns: object

add_track_to_playlistA
Idempotent

Add a track to an existing playlist.

⚠️ CAUTION: This modifies your rekordbox database!

Args: playlist_id: ID of the playlist to modify track_id: ID of the track to add

Returns: Result of the operation

Inputs: playlist_id (required), track_id (required). Returns: object

analyze_libraryB

Analyze library with grouping and aggregation.

Args: group_by: Field to group by (genre, key, year, artist, rating) aggregate_by: Aggregation method (count, playCount, totalTime) top_n: Number of top results to return

Returns: Analysis results

Inputs: group_by, aggregate_by, top_n. Returns: object

connect_databaseB

Connect to the rekordbox database.

Args: database_path: Optional path to database directory. If not provided, auto-detection is used.

Returns: Connection status message

Inputs: database_path. Returns: object

create_playlistA

Create a new playlist in rekordbox.

⚠️ CAUTION: This modifies your rekordbox database!

Args: name: Name for the new playlist parent_id: Optional parent folder ID (omit for root level)

Returns: Information about the created playlist

Inputs: name (required), parent_id. Returns: object

delete_playlistA
DestructiveIdempotent

Delete a playlist from rekordbox.

⚠️ DANGER: This permanently deletes a playlist and cannot be undone!

Args: playlist_id: ID of the playlist to delete

Returns: Result of the operation

Inputs: playlist_id (required). Returns: object

get_history_sessionsB

Get DJ history sessions from rekordbox.

Args: include_folders: Whether to include folder entries (years/months) limit: Maximum number of sessions to return

Returns: List of history sessions with metadata

Inputs: include_folders, limit. Returns: result

get_history_statsB

Get comprehensive statistics about DJ history sessions.

Returns: Statistics about all history sessions including totals and trends

Inputs: no named parameters. Returns: object

get_library_statsC

Get comprehensive library statistics.

Returns: Dictionary containing various library statistics

Inputs: no named parameters. Returns: object

get_most_played_tracksC

Get the most played tracks in the library.

Args: limit: Maximum number of tracks to return

Returns: List of most played tracks

Inputs: limit. Returns: result

get_playlistsA

Get all playlists from the rekordbox database.

Returns: List of playlists with metadata

Inputs: no named parameters. Returns: result

get_playlist_tracksC

Get all tracks in a specific playlist.

Args: playlist_id: The unique playlist identifier

Returns: List of tracks in the playlist

Inputs: playlist_id (required). Returns: result

get_recent_sessionsB

Get recent DJ history sessions within the specified number of days.

Args: days: Number of days to look back (default: 30)

Returns: List of recent history sessions

Inputs: days. Returns: result

get_session_tracksB

Get all tracks from a specific DJ history session.

Args: session_id: The session's unique identifier

Returns: List of tracks in the session with performance context

Inputs: session_id (required). Returns: result

get_top_rated_tracksB

Get the highest rated tracks in the library.

Args: limit: Maximum number of tracks to return

Returns: List of top rated tracks

Inputs: limit. Returns: result

get_track_detailsB

Get detailed information about a specific track.

Args: track_id: The unique track identifier

Returns: Detailed track information including metadata, cue points, and play history

Inputs: track_id (required). Returns: object

get_track_file_pathB

Get the file system path for a specific track.

Args: track_id: The unique track identifier

Returns: Dictionary containing file path information

Inputs: track_id (required). Returns: object

get_tracks_by_bpm_rangeB

Get tracks within a specific BPM range.

Args: bpm_min: Minimum BPM bpm_max: Maximum BPM

Returns: List of tracks within the BPM range

Inputs: bpm_min (required), bpm_max (required). Returns: result

get_tracks_by_keyC

Get all tracks in a specific musical key.

Args: key: Musical key (e.g., "5A", "12B")

Returns: List of tracks in the specified key

Inputs: key (required). Returns: result

get_unplayed_tracksB

Get tracks that have never been played.

Args: limit: Maximum number of tracks to return

Returns: List of unplayed tracks

Inputs: limit. Returns: result

remove_track_from_playlistA
Idempotent

Remove a track from a playlist.

⚠️ CAUTION: This modifies your rekordbox database!

Args: playlist_id: ID of the playlist to modify track_id: ID of the track to remove

Returns: Result of the operation

Inputs: playlist_id (required), track_id (required). Returns: object

search_history_sessionsB

Search DJ history sessions with various filters.

Args: query: Search query for session names year: Filter by year (e.g., "2025") month: Filter by month (e.g., "08" for August) min_tracks: Minimum number of tracks in session limit: Maximum number of results

Returns: List of matching history sessions

Inputs: query, year, month, min_tracks, +1 more. Returns: result

search_tracksB

Search tracks in the rekordbox database.

Args: query: General search query (searches across multiple fields) artist: Filter by artist name title: Filter by track title genre: Filter by genre key: Filter by musical key (e.g., "5A", "12B") bpm_min: Minimum BPM bpm_max: Maximum BPM rating_min: Minimum rating (0-5) limit: Maximum number of results to return

Returns: List of matching tracks with metadata

Inputs: query, artist, title, genre, +5 more. Returns: result

search_tracks_by_filenameB

Search for tracks by filename.

Args: filename: Filename to search for (partial match)

Returns: List of tracks matching the filename

Inputs: filename (required). Returns: result

validate_track_idsC

Validate a list of track IDs and show which are valid/invalid.

Args: track_ids: List of track IDs to validate

Returns: Validation results with valid and invalid IDs

Inputs: track_ids (required). Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 25 tools

    Disambiguation4/5

    Most tools have distinct purposes with clear boundaries, such as playlist management vs. track retrieval vs. analysis. However, some overlap exists between 'add_tracks_to_playlist' and 'add_track_to_playlist', which could cause confusion about when to use the batch vs. single operation, and between 'get_history_sessions' and 'get_recent_sessions', which differ only in time scope. Descriptions help clarify these distinctions, but the overlap is noticeable.

    Naming Consistency5/5

    Tool names follow a highly consistent verb_noun pattern throughout, using snake_case uniformly. Examples include 'create_playlist', 'delete_playlist', 'get_track_details', and 'search_tracks'. This predictability makes it easy for agents to understand and navigate the toolset without confusion from mixed conventions.

    Tool Count3/5

    With 25 tools, the count is borderline high for a rekordbox management server, potentially feeling heavy. While many tools are justified for comprehensive library and playlist operations, some could be consolidated (e.g., the two add-to-playlist tools) to reduce complexity. It's not extreme, but it approaches the upper limit of what's manageable.

    Completeness5/5

    The toolset provides complete coverage for rekordbox management, including CRUD for playlists (create, get, delete, add/remove tracks), extensive track retrieval (by BPM, key, rating, etc.), history session analysis, library statistics, and search capabilities. There are no obvious gaps; agents can perform all core workflows from database connection to detailed track manipulation and analysis.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers