Serato DJ library

serato-dj-mcp

向 Claude 询问你的 Serato DJ 曲库：查找 BPM 和 Camelot 调性协调的曲目，浏览你的歌箱，检查曲库中的重复曲目和缺失文件，还可以让它为你创建新的歌箱，并在写入任何内容之前展示给你。它通过 Model Context Protocol（MCP）工作，这是 Claude Desktop、Claude Code、Cursor 和 VS Code 等 AI 应用连接你电脑上工具的标准方式：这是一个小型本地服务，从你的曲库中查询信息，不会自行向任何地方发送数据。

状态：实验性。 尚未达到 1.0 版本，且正在积极开发：次要版本可能会更改行为或破坏兼容性，补丁版本则不会。

重要

与 Serato 无关联、未获其认可，也不受其支持。 Serato 和 Serato DJ 是其各自所有者的商标。本项目读取经过逆向工程分析的数据库布局，任何 Serato 更新都可能导致其无法工作。

你可以询问什么

连接服务后，你可以像平常一样与助手对话：

• “查找今年添加的、BPM 在 122 到 126 之间、调性为 8A 或 9A 的曲目。”
• “找出从 8A 调性出发、能协调混音且 BPM 约为 124 的曲目。”
• “按顺序展示 Warm Up 歌箱中的曲目。”
• “检查我的曲库：重复曲目、缺失文件，以及未归入任何歌箱的曲目。”
• “我的曲库中哪些曲目没有 BPM 或调性？”

开启歌箱写入后：

• “用你刚找到的二十首曲目创建一个名为 Friday Opening 的歌箱，并在写入任何内容之前先展示列表。”然后，在关闭 Serato 后：“应用暂存的歌箱。”

助手负责搜索；服务从你的曲库中查询信息，并且只会在你提出要求时写入你批准的内容。

安装

可在 macOS 上使用。 已在 macOS 上通过 Serato DJ Lite 4.0.9 测试；测试套件在 macOS 和 Linux 上使用 Node.js 22.16 和 24 运行。Windows 未经测试——请参阅兼容性。 Claude Desktop 扩展和下方的 Claude Code 配置已在 macOS 上手动试用；Cursor 和 VS Code 配置依据相应编辑器的文档编写，尚未试用。

所有配置都默认以只读模式启动服务。歌箱写入是单独的开关，详见下文。

Claude Desktop

作为扩展安装（无需 Node.js）。 从最新发布版本下载 serato-dj-mcp-<version>.mcpb（从 0.1.1 版本起随发布提供）并打开；Claude Desktop 会展示其中的内容并完成安装。你可以在其设置中指定曲库文件夹，并开启歌箱写入或原始 SQL；这三项都可以保持默认值。

或者手动配置，需要安装 Node.js 22.16 或更新版本：打开“设置”→“开发者”→“编辑配置”，将服务添加到 claude_desktop_config.json，然后重新启动 Claude Desktop。

{
  "mcpServers": {
    "serato": {
      "command": "npx",
      "args": ["-y", "serato-dj-mcp"]
    }
  }
}

Claude Code

claude mcp add serato -- npx -y serato-dj-mcp

在 serato 前添加 --scope user，即可在每个项目中使用。此仓库也是一个 Claude Code 插件，会启动相同的命令。

Cursor

添加到 Cursor，或在 ~/.cursor/mcp.json 中添加与 Claude Desktop 相同的 mcpServers 条目。该链接会打开 cursor://anysphere.cursor-deeplink/mcp/install?name=serato&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsInNlcmF0by1kai1tY3AiXX0=，并请求 Cursor 在名称 serato 下添加 {"command":"npx","args":["-y","serato-dj-mcp"]}。

VS Code

在 VS Code 中安装， 或在终端中运行：

code --add-mcp '{"name":"serato","type":"stdio","command":"npx","args":["-y","serato-dj-mcp"]}'

适用于任何客户端的选项

在 args 中的 serato-dj-mcp 后添加选项，例如 "args": ["-y", "serato-dj-mcp", "--allow-writes"]：

• --library <path> — Serato 资料库文件夹（包含 master.sqlite 的文件夹）。macOS 上无需指定， 系统会自动找到 ~/Library/Application Support/Serato 中以及已挂载驱动器上的资料库。
• --allow-writes — 允许写入 crate，见下文。
• --allow-raw-sql — 添加 run_sql，供开发者使用的只读 SQL 工具。

所有选项都列在选项中。

node:sqlite 是实验性的 Node API，会向 stderr 打印警告；这是正常且无害的，因为 MCP 协议通过 stdout 传输。

从源代码构建（供开发者使用）

git clone https://github.com/Venut-Technologies/serato-dj-mcp.git
cd serato-dj-mcp
npm ci
npm run build

然后使用 "command": "node" 和 "args": ["/absolute/path/to/serato-dj-mcp/dist/index.js"]，或 claude mcp add serato -- node /absolute/path/to/serato-dj-mcp/dist/index.js。

有关服务读取、写入和发送的内容，请参阅 PRIVACY.md：它不会发起网络请求，也不收集遥测数据。

兼容性

Serato DJ 4.x	支持。开发和测试均基于 Serato DJ Lite 4.0.9（资料库架构 202）。其他 4.x 架构版本会读取，并发出 schema_unknown 警告。预计 Serato DJ Pro 4.x 使用相同的资料库格式，但尚未经过测试。
Serato DJ 3.x	可检测并报告，但不会读取（它使用二进制 database V2，而非 SQLite）。
macOS	支持。项目在此平台上开发，CI 也在此平台上运行。
Windows	未经测试。服务没有针对 Windows 的专门处理：请明确传入 --library，因为自动发现只识别 macOS 布局；并且请注意，用户文件夹下会使用 macOS 风格的缓存和状态目录。“Serato 是否正在运行”检查使用了 Windows 不具备的 ps，因此 apply_changes 可能会拒绝写入，而不会冒险进行猜测。
Linux	Serato 无法在 Linux 上运行；测试套件会在 CI 中使用合成测试数据运行。
Node.js	22.16 或更高版本，因为 node:sqlite 中的 backup() 从该版本开始提供。此版本要求并非凭空假设：CI 会在 macOS 和 Ubuntu 上分别使用 22.16 和 24 运行完整测试套件。
Claude Desktop 扩展	在 Claude Desktop 自带的 Node.js 中运行，而非你安装的版本。于 2026-09-24 在 macOS 上通过 Claude Desktop 2.7032.0 手动检查，其内置 Node.js 版本为 24.21：安装后，list_libraries 和 list_crates 均返回了资料库数据。

此服务对 Serato 资料库的所有假设都记录在 docs/serato-4x-notes.md 中，每条说明后都附有相应的测量依据。

默认只读，按需写入

默认情况下，此服务绝不会写入 Serato 文件。 每次读取都会通过 --cache-dir 中的资料库数据库快照副本进行， 因此，无论 Serato 是否打开，助手都无法通过提问更改你的资料库。

两个标志可扩展此功能，且只有在指定时才会注册相应的额外工具——不存在的工具就不可能被误调用：

• --allow-raw-sql 会添加 run_sql：针对快照执行只读 SELECT，并返回原始行。
• --allow-writes 会添加 stage_crate、preview_changes、apply_changes 和 discard_changes。 写入分为两步：先暂存 crate，此操作不会触及资料库；只有在你确认且 Serato 已关闭后，才会应用更改。每次写入前都会备份两个数据库。详情请参阅写入资料库。

工具

• list_libraries — 此服务可访问的库，包括版本、架构版本和位置。此处的路径不会被隐藏，因此可以将其中一个复制到 --library。
• search_tracks — 按自由文本、BPM、调性、流派、评分、添加日期、唱片箱归属和标记搜索。调性采用 Camelot 记法；即使 Serato 本身无法解析某首曲目的调性，该曲目仍会匹配，key_source 会说明调性的来源。支持分页，使用不透明游标；默认页包含 25 首曲目和 9 个字段。
• get_tracks — 根据 search_tracks 返回的 ID 获取曲目。未知 ID 会列在 missing 中，不会被丢弃。
• list_crates — Serato Library 空间中的唱片箱，包含其显示路径和各自包含的不同曲目数量。不会列出智能唱片箱、空间根目录和 Serato 的其他内部空间（例如 Prepare 面板）。
• get_crate_tracks — 按唱片箱自身的顺序返回其中的曲目。只能指定 Serato Library 空间中的唱片箱。
• audit_library — 诊断库。默认运行所有检查，并报告数量以及最多 10 个示例曲目 ID：没有 BPM、完全没有调性、Serato 本身无法显示调性、标记为过时、不属于任何唱片箱、仅来自流媒体、重复以及路径损坏的曲目。duplicates 会报告分组，而非单独的 ID，因为知道哪首曲目重复了哪首曲目才便于采取操作。默认情况下，broken_paths 会读取 Serato 自身的缺失标记；传入 check_filesystem: true 还会检查磁盘。此项默认关闭，因为对已断开连接的驱动器执行 stat 会阻塞数秒。未挂载的驱动器会被报告为未挂载，而不会将其中所有曲目都判定为缺失。
• run_sql — 针对快照副本执行一条只读 SELECT。只有使用 --allow-raw-sql 才会注册，因为它会返回未经路径隐藏处理的原始行。

使用 --allow-writes 时：

• stage_crate — 根据曲目 ID 暂存一个新唱片箱。此时尚未写入任何内容；响应会按标题和艺人列出每首已暂存曲目，请检查。
• preview_changes — 显示暂存的内容，使用 format: "detail" 可细化到每首曲目。
• apply_changes — 写入所有已暂存内容，要么全部写入，要么全部不写入。Serato 正在运行时会拒绝执行。
• discard_changes — 丢弃一个已暂存唱片箱，或全部丢弃。

选项

--library <path>、--root <dir>（可重复）、--cache-dir <dir>、 --state-dir <dir>、--allow-raw-sql、--allow-writes、--help、 --version。SERATO_LIBRARY_PATH 可替代 --library； 若同时指定，两者以该标志为准。未知选项会报错，不会被忽略。

写入曲库

写入需要使用 --allow-writes，并分两步进行，因为写入数据库时 Serato 必须关闭，而模型通常会在 Serato 打开时工作。stage_crate 可以随时运行；Serato 正在运行时，apply_changes 会拒绝执行。之后启动 Serato，新建的歌单会在几秒内出现。

写入的内容：在 Serato 曲库顶层的 root.sqlite 中创建新歌单，仅此而已。它绝不会更改或删除现有歌单，不会编辑曲目，也不会触及 master.sqlite、database V2 或 Subcrates 文件夹——这些内容由 Serato 自行重新生成。

每次写入前，都会将两个数据库备份到 <state-dir>/backups/<library-id>/<timestamp>/（默认 state-dir： ~/Library/Application Support/serato-dj-mcp），并保留最近十份备份。每次 apply_changes 尝试只要进入备份步骤，就会创建备份，包括随后在事务中遭拒的尝试（例如名称冲突）——因此，“最近十份”指最近十次尝试，而不是十次成功写入；最新的备份可能已经包含你正试图撤销的写入。

没有撤销工具。 要撤销某次特定写入，先找到对应的备份：使用该次 apply_changes 调用返回的 backup_paths，或打开 <state-dir>/manifests/<library-id>.jsonl，找到 "commit_state" 为 "committed" 的那一行，并取出其 backup_paths。<library-id> 是 list_libraries 报告的 uuid。拿到这两个路径后：

1. 退出 Serato。
2. 在曲库文件夹中，如果存在 root.sqlite-journal，请将其删除；并删除 master.sqlite-wal 和 master.sqlite-shm。
3. 将备份的 root.sqlite 和 master.sqlite 复制到曲库文件夹，替换当前文件。
4. 删除 ~/Music/_Serato_/Subcrates/<crate name>.crate——Serato 在同步歌单后导出了它，而复制回数据库不会将其删除。

恢复这些文件也会回滚备份创建后 Serato 自行记录到曲库中的所有内容。

不支持嵌套歌单：通过此方式在另一个歌单内创建的歌单，会在 Serato 下次同步时被删除，因此所有歌单都会创建在顶层。

隐私

内容相同，并以独立政策的形式呈现，每条说明后都附有对应的源文件： PRIVACY.md。

• 所有操作都在你的电脑上运行。 MCP 服务是由你的 MCP 客户端启动的本地进程。它不发送遥测数据，没有分析功能，也不会发起网络请求。它运行的唯一其他程序是 ps，用于在写入前检查 Serato 是否正在运行。
• 读取的内容： Serato 的曲库数据库，除 apply_changes 外始终以只读方式访问；当 audit_library 的 check_filesystem: true 时，还会读取磁盘上曲目的文件元数据。
• 写入的内容及位置：
  • --cache-dir（默认 ~/Library/Caches/serato-dj-mcp）用于保存曲库数据库的快照副本。可随时安全删除。
  • --state-dir（默认 ~/Library/Application Support/serato-dj-mcp）用于保存暂存的歌单、每次写入的清单、锁文件和曲库数据库备份。仅在使用 --allow-writes 时使用。删除此目录会一并删除这些备份。
  • 使用 --allow-writes 时，apply_changes 会将新歌单写入 Serato 的 root.sqlite。
• 哪些内容会离开你的电脑，取决于你的 MCP 客户端。 工具结果——曲目标题、艺人、歌单名称、文件路径——会发送给你的助手，然后传给客户端使用的模型提供商。你主目录下的曲目路径会缩写为 ~；list_libraries、run_sql 和 apply_changes 返回的备份路径则是完整路径。如果你在意这一点，请查看客户端的数据政策。

限制

决定信任哪些内容之前，请先阅读本节。

• 不支持 Serato DJ 3.x。 系统可以识别并报告为 version: "3.x"，但不会读取其中的数据——它使用的是二进制 database V2， 而非 SQLite。任何工具都无法从 3.x 曲库中返回数据。
• 读取操作通过快照进行，因此答案反映的是最近一次快照时的曲库状态， 而非当前时刻。快照会复用至多两秒，因此 Serato 写入期间，答案最多可能滞后两秒。 --cache-dir 中只保留每个曲库的当前快照；一旦发布更新的快照， 旧快照就会立即删除。
• 有两项审计检查依赖本项目尚未确认含义的列。 stale 读取 is_stale，streaming_only 读取 third_party_type；在参考曲库的每首曲目中， 这两列的值都为零，因此这里只报告计数，不声称这些列代表什么。
• rating 和流媒体标记会原样传递，不作解释。 参考曲库的全部 118 首曲目中， rating 均为 NULL 或 0，因此尚未确认评分的最高值。对于流媒体标记， 除原始列值外，不对其含义作任何断言。
• 对 analysis_flags 的位 2 作出说明，但不说明该字段的其他部分。 它被视为“Serato 执行了自己的分析”——这与“有 BPM”并不相同， 因为 BPM 也可能来自文件标签——并作为 flags.analyzed 暴露， search_tracks 可按此筛选。2026-09-06 对 118 首曲目的测量结果： 106 首设置了位 2，其中 104 首有 BPM；12 首未设置该位——其中 6 首是音效， 另有 6 首的 BPM 来自标签，而非 Serato 自行分析。
• 自由文本搜索并非 Serato 的搜索。 Serato 使用只有其自身进程才具备的函数来规范化文本， 因此 q 会同时匹配规范化列和原始列，结果可能与应用程序搜索到的内容不同。
• 在 Serato 写入期间获取的分页可能跨越两个快照。 分页采用键集方式， 因此会从较新副本中的相同位置继续，并通过 warnings: snapshot_advanced 表明这一点；交界处可能会重复或跳过少量行。
• 写入 crate 是新功能，仍处于实验阶段。 写入协议是在运行中的 Serato DJ Lite 4.0.9 曲库上摸索出来的，但尚未在不同 Serato 更新版本、大型曲库 或分布在外置硬盘上的曲库中测试。请同时保留自己的备份。
• 写入范围有意限定得很窄。 apply_changes 只会创建顶层 crate，不会执行其他操作： 不创建嵌套 crate 或智能 crate，不重命名、重排或删除 crate，也不编辑曲目、 提示点或其他元数据。
• crate 只能包含来自曲库所在磁盘的曲目。 stage_crate 会拒绝流媒体曲目， 以及存放在其他硬盘的 Serato 存储区中的曲目，并逐一列出它们。
• 应用更改时必须关闭 Serato，之后必须重启才能看到结果。 只有在 Serato 启动并完成同步后， 新 crate 才会显示在 Serato 和此服务的读取工具中。
• 暂存时会读取 Serato 的实时数据库。 Serato 可能正在运行时，stage_crate 会读取 root.sqlite。2026-09-16 的测量结果：对 50 首曲目进行 3 次暂存， 每次耗时 8 至 41 毫秒；Serato 自身的日志在这几秒内没有记录。这只是证据， 并非保证——尚未测试繁忙曲库，或 Serato 正在写入的情况。
• 没有撤销工具。 撤销写入需要按照上文所述手动恢复备份。

原则

此服务对你的曲库作出的保证，以及它拒绝执行的操作，都列于 PRINCIPLES.md——每项保证都附有用于强制执行的代码，以及在该保证失效时会失败的测试。

安全

请私下报告漏洞，参见 SECURITY.md。请勿为此创建公开议题。

参与贡献

欢迎提交议题和拉取请求；请从 CONTRIBUTING.md 开始。更改记录见 [CHANGELOG.md](CHANGELOG.md]。

许可证

MIT。由 Venut Technologies 维护。

Serato 和 Serato DJ 是其各自所有者的商标。本项目独立开发，与 Serato 无关联，也未获其认可或支持。