Rekordbox MCP 服务器

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

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