Serato DJ library

serato-dj-mcp

Ask Claude about your Serato DJ library: find tracks that mix harmonically by BPM and Camelot key, browse your crates, audit the library for duplicates and missing files, and have new crates built for you, shown to you before anything is written. It works through the Model Context Protocol (MCP), the standard way AI apps such as Claude Desktop, Claude Code, Cursor and VS Code connect to tools on your computer: this is a small local server that answers from your library and sends nothing anywhere itself.

Status: experimental. Pre-1.0 and actively developed: a minor version may change behaviour or break compatibility, a patch never does.

[!IMPORTANT]

Not affiliated with, endorsed by, or supported by Serato. Serato and Serato DJ are

trademarks of their respective owner. This project reads a reverse-engineered database layout

and can stop working after any Serato update.

What you can ask

Once the server is connected, you talk to your assistant as usual:

• "Find tracks between 122 and 126 BPM in 8A or 9A that I added this year."
• "Give me tracks that mix harmonically out of 8A, around 124 BPM."
• "Show me what's in my *Warm Up* crate, in order."
• "Audit my library: duplicates, missing files, tracks that aren't in any crate."
• "Which tracks in my library have no BPM or no key?"

With crate writing switched on:

• "Build a crate called *Friday Opening* from the twenty tracks you just found, and show me the list before writing anything." Then, once you have closed Serato: "Apply the staged crate."

The assistant does the searching; the server answers from your library and, when asked, writes only what you approved.

Install

Works on macOS. Tested with Serato DJ Lite 4.0.9 on macOS; the test suite runs in CI on macOS and Linux with Node.js 22.16 and 24. Windows is untested — see Compatibility. The Claude Desktop extension and the Claude Code setup below were tried by hand on macOS; the Cursor and VS Code setups follow those editors' documentation and have not been tried.

Every setup starts the server read-only. Crate writing is a separate switch, described below.

Claude Desktop

As an extension (no Node.js needed). Download serato-dj-mcp- .mcpb from the latest release (attached from version 0.1.1 on) and open it; Claude Desktop shows what it contains and installs it. Its settings let you point it at a library folder and switch on crate writing or raw SQL; all three can stay as they are.

Or by hand, with Node.js 22.16 or newer installed: open Settings → Developer → Edit Config and add the server to claude_desktop_config.json, then restart Claude Desktop.

{

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

Claude Code

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

Add --scope user before serato to have it in every project. The repository is also a Claude Code plugin that starts the same command.

Cursor

Add to Cursor, or add the same mcpServers entry as for Claude Desktop to ~/.cursor/mcp.json. The link opens cursor://anysphere.cursor-deeplink/mcp/install?name=serato&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsInNlcmF0by1kai1tY3AiXX0=, which asks Cursor to add {"command":"npx","args":["-y","serato-dj-mcp"]} under the name serato.

VS Code

Install in VS Code, or from a terminal:

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

Options for any client

Add options after serato-dj-mcp in args, for example "args": ["-y", "serato-dj-mcp", "--allow-writes"]:

• --library — the Serato library folder (the one holding master.sqlite). Not needed on macOS, where the library in ~/Library/Application Support/Serato and on mounted drives is found automatically.
• --allow-writes — crate writing, see below.
• --allow-raw-sql — adds run_sql, read-only SQL for developers.

All options are listed under Options.

node:sqlite is an experimental Node API and prints a warning to stderr; that is expected and harmless, because the MCP protocol travels over stdout.

From source, for developers

git clone https://github.com/Venut-Technologies/serato-dj-mcp.git

cd serato-dj-mcp npm ci npm run build

Then use "command": "node" with "args": ["/absolute/path/to/serato-dj-mcp/dist/index.js"], or claude mcp add serato -- node /absolute/path/to/serato-dj-mcp/dist/index.js.

What the server reads, writes and sends is in PRIVACY.md: it makes no network requests and has no telemetry.

Compatibility

Everything this server assumes about the Serato library is written down in docs/serato-4x-notes.md, with the measurement behind each claim.

Read-only by default, writes on request

By default the server never writes to Serato's files. Every read goes through a snapshot copy of the library database in --cache-dir, so a question from the assistant cannot change your library, whether Serato is open or not.

Two flags widen that, and each registers extra tools only when it is given — a tool that does not exist cannot be called by mistake:

• --allow-raw-sql adds run_sql: read-only SELECT against the snapshot, returning raw rows.
• --allow-writes adds stage_crate, preview_changes, apply_changes and discard_changes. Writing is split in two: crates are *staged* first, which never touches the library, and are *applied* only when you confirm and Serato is closed. Both databases are backed up before every write. The details are in Writing to the library.

Tools

• list_libraries — the libraries this server can see, with version, schema version and locations. Paths here are not redacted, so you can copy one into --library.
• search_tracks — search by free text, BPM, key, genre, rating, date added, crate membership and flags. Tonality is Camelot; a track whose key Serato itself could not parse is still matched, and key_source says where the key came from. Paginated with an opaque cursor; the default page is 25 tracks and nine fields.
• get_tracks — fetch tracks by the ids search_tracks returned. Unknown ids come back in missing rather than being dropped.
• list_crates — the crates in the Serato Library space, with their display path and how many distinct tracks each holds. Smart crates, space roots and Serato's other internal spaces (such as the Prepare panel) are not listed.
• get_crate_tracks — the tracks of one crate, in the crate's own order. Only crates in the Serato Library space can be given.
• audit_library — diagnose the library. Every check runs by default and reports a count plus up to ten example track ids: tracks with no BPM, with no key at all, with a key Serato itself cannot display, marked stale, in no crate, streaming-only, duplicated, and with broken paths. duplicates reports groups instead of loose ids, because which track duplicates which is the part you can act on. broken_paths reads Serato's own missing flag by default; pass check_filesystem: true to also look on disk, which is opt-in because a stat against a disconnected drive blocks for seconds. A drive that is not mounted is reported as such rather than having all its tracks declared missing.
• run_sql — one read-only SELECT against a snapshot copy. Registered only with --allow-raw-sql, because it returns raw rows with no path redaction.

With --allow-writes:

• stage_crate — stage a new crate from track ids. Nothing is written yet; the response lists every staged track by title and artist, so check it.
• preview_changes — show what is staged, with format: "detail" down to each track.
• apply_changes — write everything staged, all or nothing. Refused while Serato is running.
• discard_changes — drop one staged crate, or all of them.

Options

--library , --root (repeatable), --cache-dir , --state-dir , --allow-raw-sql, --allow-writes, --help, --version. SERATO_LIBRARY_PATH is an alternative to --library; the flag wins. An unknown option is an error, not a no-op.

Writing to the library

Writes need --allow-writes and happen in two steps, because Serato must be closed while its database is written and the model usually works while it is open. stage_crate can run at any time; apply_changes refuses while Serato is running. Start Serato afterwards and the new crates appear within a few seconds.

What a write does: it creates new crates at the top level of the Serato Library, in root.sqlite, and nothing else. It never changes or deletes an existing crate, never edits a track, never touches master.sqlite, database V2 or the Subcrates folder — Serato regenerates those itself.

Before every write both databases are backed up under /backups/ / / (default state-dir: ~/Library/Application Support/serato-dj-mcp), and the last ten are kept. A backup is taken on every apply_changes attempt that reaches the backup step, including attempts that are then refused inside the transaction (a name conflict, for example) — so "the last ten" means the last ten *attempts*, not ten successful writes, and the newest one may already contain the write you are trying to undo.

There is no undo tool. To undo a specific write, first find the right backup: use the backup_paths returned by that apply_changes call, or open /manifests/ .jsonl and take the backup_paths of the line whose "commit_state" is "committed". is the uuid reported by list_libraries. Then, with that pa