
traktor-mcp
io.github.alchimestre/traktor-mcp
Inspect and reconcile a Traktor collection: preview changes, import tracks and purge missing files.
Documentation
traktor-mcp
Inspect and reconcile your Traktor collection from an MCP client.
Uses traktor-nml to update collection.nml when audio files are replaced or added, without editing XML by hand.
| Requirement or limit | Detail |
|---|---|
| Runtime | Python 3.13+, uv |
| Client | Local MCP server support over stdio |
| Files | Access to the Traktor collection and music directories on the same machine |
| Scope | Collection maintenance, not playback or live deck control |
| Status | Early version: 0.1.0 |
| Licence | MIT |
Setup
-
Install from PyPI:
uv tool install traktor-mcp -
Check that the executable is on your PATH:
traktor-mcp --helpIf the command is not found, add the directory printed by
uv tool dir --binto your PATH. -
Create
traktor.toml. The default collection is inDocuments/Native Instruments/Traktor <version>/collection.nml; replace the paths below with your actual locations:[paths] collection = "/path/to/Traktor/collection.nml" lossless = "/path/to/music/lossless" lossy = "/path/to/music/lossy"losslessandlossyare the music directories to import from. Relative paths resolve against the configuration file's directory. Addstateonly if a local pipeline tracks file replacements there: its<run>/tracks.jsonlrecords withreplacesandlocal_pathidentify replacement files. Without that data, replacement matching uses filenames. Check the reported collection path before approving a write. -
Add the server to your MCP client's configuration. For clients using
mcpServers, merge this entry into the existing object:{ "mcpServers": { "traktor": { "command": "traktor-mcp", "args": ["--config", "/path/to/traktor.toml"] } } }Replace the config path with an absolute path. If the client cannot find
traktor-mcp, use the executable's absolute path from step 2. Other clients may use a different configuration wrapper; the command and arguments stay the same. -
Restart or reload the client, then ask: “Call Traktor's
statusandplan. Show the proposed changes without writing anything.”planreports entries to repoint, files to add, and missing files. Check the reported collection path before approving a write.
Tools
| Tool | Writes to collection | Effect |
|---|---|---|
status | No | Summarise the collection and configured music directories |
plan | No | List proposed replacements, additions and missing files |
apply | Yes | Repoint replaced files and add new files; remove no entries |
purge | Only with apply: true | Remove entries whose files are missing; preview by default |
Files in lossless and lossy are candidates for import. Files elsewhere are reported rather than moved.
For shell use without an MCP client, use traktor-nml directly.
Before writing
- Close Traktor. It rewrites the collection on exit and can overwrite external changes. Both write operations refuse while Traktor is running.
- Call
planand inspect its output.applywrites immediately when called; it has no separate confirmation argument. - Call
applyonly after reviewing replacements and additions. It backs up the collection beside the original before writing; untouched entries retain their original XML. - Preview
purgeseparately before calling it withapply: true. Removed entries lose their history, cues and play counts. Playlist references are reassigned to a retained entry or dropped. A backup is taken before writing. - Open Traktor and run Check Consistency → Analyze for replaced tracks. Their old fingerprint, tempo, loudness, key and beatgrid measurements must be regenerated.
Development
-
Install the project and development dependencies:
uv sync -
Run the tests:
uv run pytest
To work on the library alongside the server, override it with a sibling checkout:
uv pip install -e ../traktor-nml
Publishing
-
Configure a PyPI Trusted Publisher for this GitHub repository, workflow
publish.yml, environmentpypi. -
Dispatch the workflow from
mainwith the release tag or commit SHA asref:gh workflow run publish.yml --repo alchimestre/traktor-mcp --ref main -f ref=v0.1.0 -
Check the workflow result before announcing the release. Published PyPI versions cannot be overwritten.
traktor-mcppip install traktor-mcp