Engine DJ Library Assistant (unofficial)

engine-dj-mcp

Ask Claude, or any AI assistant, about your Engine DJ library: find tracks by BPM, key, genre or your own comments, check the collection for duplicates, missing files and tracks with no cues, read the cues and beatgrids Engine stored, and have playlists built or track tags fixed when you ask. It works through MCP, the Model Context Protocol, the standard way AI apps such as Claude Desktop, Claude Code, Cursor and VS Code connect to tools on your own computer: the app starts this server, and the assistant calls it when a question needs your library.

It reads the library on your computer and the ones on your USB drives. It opens them read-only at the operating-system level and changes nothing unless you start it with --allow-writes — then it can create and edit playlists and edit genre, comment, label, year and rating, and it copies the whole database to a backup before the first change. See Safety. The server itself sends nothing anywhere; what your AI app does with its answers is covered in PRIVACY.md.

Status: Active · Pre-1.0. In regular use and maintained; before 1.0 a MINOR release may change behaviour, a PATCH never does. Changes are recorded in CHANGELOG.md.

**Not affiliated with, endorsed by, or sponsored by inMusic Brands, Denon

DJ, or the Engine DJ product.** "Engine DJ" is used here only to name the

software whose library this tool reads and writes. No logos or brand

artwork from inMusic or Denon DJ are used in this project.

What you can ask

Once connected, these are ordinary questions in chat:

• *"Something dark around 124 in a minor key I haven't played in six months."*
• *"Find me anything harmonically compatible with 8A between 138 and 142."*
• *"What's broken in my collection — missing files, duplicates, tracks with no cues?"*
• *"Where are the cue points on this track, and what tempo did Engine analyse?"*
• *"Build me a playlist of everything in 5A from 140 BPM up."* (needs --allow-writes)
• *"Set the genre of these five tracks to Minimal and rate them four stars."* (needs --allow-writes)

Install

You need Node.js 22.16 or newer. There is nothing else to install: every app below starts the server with npx, which downloads it from npm the first time.

npx engine-dj-mcp

That command is what the apps run; you do not need to run it yourself.

Claude Desktop

Settings → Developer → Edit Config, and add to claude_desktop_config.json:

{

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

Restart Claude Desktop.

Claude Code

claude mcp add --scope user engine-dj -- npx -y engine-dj-mcp

Cursor

Add to Cursor — or open this deep link directly, or add the same mcpServers entry as for Claude Desktop to ~/.cursor/mcp.json:

cursor://anysphere.cursor-deeplink/mcp/install?name=engine-dj&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImVuZ2luZS1kai1tY3AiXX0%3D

VS Code

Add to VS Code — or run:

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

Gemini CLI

gemini extensions install https://github.com/Venut-Technologies/engine-dj-mcp

The extension manifest (gemini-extension.json) starts the same read-only server as the entries above.

Letting it write

To let the assistant create and edit playlists and edit track tags, add --allow-writes to args — a flag rather than an environment variable precisely so it is visible in the configuration you are reading:

{

"mcpServers": { "engine-dj": { "command": "npx", "args": ["-y", "engine-dj-mcp@0.18.0", "--allow-writes"] } } }

Pin the version in this one. Unpinned, npx fetches whatever is newest at every launch, and this configuration gives that code write access to your library. Pinned, a new release reaches it only when you change the number. Quit Engine DJ before asking for a change; see Writing.

Compatibility

• macOS: yes. Every check against a real library has been run on macOS, and it finds libraries where Engine DJ keeps them there: ~/Music and the top of each drive under /Volumes.
• Windows and Linux: not supported yet. The test suite passes on Ubuntu, but no real library has been read on either system. Off macOS the server looks only in ~/Music/Engine Library, so a library on a USB drive is not found, and there is no option to point it somewhere else.
• Node.js 22.16 or newer, with no native dependencies. node:sqlite stopped needing a flag in 22.13, but the pre-write backup uses its backup(), added in 22.16. CI runs the full suite on Node 22.16 and 24, on macOS and Ubuntu.
• Engine DJ libraries at schema 3.0.0 through 3.0.2 — Engine DJ 4.5 and 5.x. Everything here has been exercised against a real schema 3.0.2 library; 3.0.0 and 3.0.1 are accepted by the version check and covered by generated fixtures, but no real library at those versions has been read. Anything outside the range is listed with its version and refused, never read on a guess.

Tools

Nine read-only tools, and five that write — create_playlist, add_tracks_to_playlist, remove_tracks_from_playlist, reorder_playlist and update_track_metadata — that appear only when you start the server with --allow-writes. Every tool that reads library data also accepts an optional library argument — see Choosing a library.

search_tracks

The main one. Full-text search with diacritics folded, plus filters for tempo, key, rating, when a track was added and when it was last played.

get_tracks

Full metadata for specific track ids, returned in the order you asked for. Unknown ids are omitted rather than failing the call.

ids (required), fields, redact_paths.

get_playlists

Your playlist tree, in the order Engine DJ shows it — folders included.

The list is flat and in the order you would read down the sidebar with every folder expanded: depth and path carry the nesting, parent_id names the folder a list sits in.

limit (default 200, max 1000). warnings appears if a playlist's link chain is damaged; nothing is ever dropped from the list because of one.

get_playlist_tracks

The tracks of one playlist, in playlist order.

Name it with playlist_id or with playlist_name — exactly one of the two. Playlist names are unique only within a folder, so a name matching more than one is refused with every candidate's id and full path rather than guessed at; pass the path from get_playlists to say which you meant.

Every row carries position, its 1-based place in the playlist. Same fields, limit and cursor conventions as search_tracks.

An entry whose track is not in this library keeps its slot and comes back as { position, entry_id, track_id, missing: true }, with missing_count alongside entry_count. That is ordinary rather than corruption — playlist entries outlive their tracks and travel between drives — and they are kept in place so the number of rows still matches the playlist's own length. On one reference library a 43-entry playlist holds exactly one track that library can actually play.

get_track_performance

Decodes the binary PerformanceData Engine stores per track: hot cues, the main cue, saved loops, the beatgrid, and a coarse waveform profile.

Every field carries its own decode status and its own layout marker. layout: "verified" means the byte layout was confirmed against a real library, so status: "ok" is a claim about the values. layout: "unverified" would mean only that the bytes parsed; no field returns it today.

Positions are sample offsets; cue and loop items also carry seconds. items: [] with slots: 8 means an analysed track with no cues set.

id (required).

audit_library

Eleven collection health checks. Returns a count and a small sample of ids per check, never the full result set — a library with thousands of unanalysed tracks should not fill an assistant's context.

| path_form_mismatch | The file is on disk, but its name there — or a folder's on the way — is in a different Unicode form from the path Engine stored. macOS finds it anyway; Linux does not (measured on the kernel's exFAT driver