Set Planner
This server helps DJs plan and time sets from track metadata, without touching audio files.
plan_set: times an ordered set using cue A/B points, transition overlaps, and a default overlap; returns a timeline, transitions, summary (total runtime, segment sum, time saved by blending), and warnings.suggest_next: ranks next-track candidates by BPM (including half/double time), Camelot key compatibility, genre overlap, and energy change; returns ranked candidates with reasons, score breakdowns, and cautions.Accepts input inline as JSON or from file paths (
input_path,library_path), and supports a CLI equivalent (shadow-set-planner plan/suggest).Works purely on track JSON: no audio files, no Rekordbox/Serato databases, fully offline and read-only.
Flexible metadata input: cue names like A/B, intro/outro, in/out, start/end; keys as Camelot or musical notation; genres as a list or comma-separated string; optional transitions.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Set Planner how long will my set run with these tracks and 16s overlaps?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Set Planner
An MCP server for the maths a DJ normally does in their head: how long will this set run, and what should I play next?
把 DJ 平时在脑子里算的事交给它:这套 set 一共多长时间、下一首该放什么(打分完全可解释)。
Works with any MCP-compatible agent or client.
Platform support: macOS — supported (developed & verified on this machine) · Windows — unverified (paths are cross-platform in the codebase, but no real-machine testing yet).
Features
Set timing. Turns cue A/B points into per-track segments, transition overlaps, phrasing warnings and one total runtime.
Next-track suggestions. Ranks candidates by bpm (half/double time included), key compatibility, genre overlap and energy change — and explains every score.
Nothing is opened. It works purely on the track JSON you give it; no audio files, no Rekordbox/Serato databases.
Explainable. Each suggestion comes with reasons, a score breakdown and cautions; each plan comes with explicit warnings instead of silent guesses.
Related MCP server: spotify-dj
Requirements
OS | macOS, Linux or Windows |
Python | 3.9 or newer |
Runtime deps | none |
Install
As a Codex plugin
codex plugin marketplace add shadowroommusic/set-planner
codex plugin add set-planner@shadowroomIn any other MCP client
{
"mcpServers": {
"set-planner": {
"command": "python3",
"args": ["mcp_server.py"],
"cwd": "/path/to/set-planner"
}
}
}CLI only
python3 -m venv .venv
.venv/bin/pip install -e .
.venv/bin/shadow-set-planner --helpInput format
{
"tracks": [
{
"id": "track-1",
"title": "Warehouse Tool",
"bpm": 128,
"key": "8A",
"genres": ["techno", "melodic techno"],
"energy": 6,
"duration_ms": 360000,
"cues": [
{ "name": "A", "position_ms": 15000 },
{ "name": "B", "position_ms": 210000 }
]
}
],
"transitions": [
{ "from": "track-1", "to": "track-2", "overlap_ms": 16000 }
]
}cues accepts A/B, intro/outro, in/out, start/end and loop cues with end_ms;
key accepts Camelot (8A) or musical notation (A minor, Am, G#m, Db); genres accepts a
list or a comma-separated string; transitions is optional.
Tools
Tool | What it does |
| Time an ordered set ( |
| Rank what to play next ( |
CLI equivalents: shadow-set-planner plan and shadow-set-planner suggest.
Usage
# time an ordered set (16 second blends here)
.venv/bin/shadow-set-planner plan --input set.json --overlap-ms 16000 --output plan.json
# what should follow the track that is playing now?
.venv/bin/shadow-set-planner suggest --library library.json --current track-1 --limit 5plan reports a timeline (segments, play positions, cue points, overlaps), transitions,
a summary (total runtime, segment sum, time saved by blending) and warnings. suggest reports
ranked candidates with reasons, breakdown and cautions.
Safety
Read-only and offline: no audio files or vendor databases are touched.
All input comes from the JSON you provide; plans and suggestions are just files (or stdout).
Troubleshooting
Symptom | What to do |
“missing A/B cues” warnings | Add |
Suggestions look flat | Give tracks |
Tempo jumps flagged | That warning means Beat Sync or pitch adjustment is needed at the transition. |
Contributing
See CONTRIBUTING.md. Implementation notes live in docs/internals.md.
License
AGPL-3.0 — see LICENSE.
Available Tools
2 toolsplan_setC
Time an ordered set: cue A/B segment lengths, transition overlaps, warnings and total runtime.
Inputs: set, input_path, default_overlap_ms.
suggest_nextC
Rank the next tracks for a current track using bpm, Camelot key, genre and energy.
Inputs: pool, limit, current, min_score, +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 2 tools
The two tools have clearly distinct purposes: plan_set handles timing and runtime of an ordered set, while suggest_next ranks next-track recommendations. There is no meaningful overlap that would confuse tool selection.
Both names use snake_case and begin with an imperative verb, making them predictable. The second word differs slightly in type (noun 'set' vs. adjective/adverb 'next'), but the pattern is still clear.
Two tools feels thin for a server named Set Planner, which likely implies broader set-building and management functionality. The tools themselves are focused, but the surface is borderline under-scoped.
The set covers core timing and next-track suggestion but lacks set CRUD, save/export, track metadata lookup, and energy-curve editing. These are notable gaps for a full set-planning workflow.
Maintenance
Related MCP Connectors
Audio features + harmonic set-building for tracks by name/ISRC. Spotify audio-features replacement.
Check if two songs mix (Camelot key, BPM), read shared song DNA reports, tempo and nightcore math.
Identify the tracklist of any DJ mix from its YouTube, SoundCloud or Mixcloud URL.
Find the tracks DJs play in Instagram, TikTok and set links; ask about your DJs, feed and sets.
Related MCP Servers
- AlicenseAqualityBmaintenanceEnables AI assistants to control Spotify playback, manage playlists, and plan DJ sets using BPM, key, and energy data.37MIT
- AlicenseNot gradedqualityBmaintenanceEnables DJs to retrieve BPM, key/Camelot, energy, and other track metadata with provider provenance, score transitions, plan setlists, and control Spotify playlists and playback with staged, revalidated writes for safety.MIT
- AlicenseAqualityBmaintenanceEnables AI assistants to search and audit a Serato DJ library by BPM and Camelot key, browse crates, detect duplicates and missing files, and stage new crates for review before writing.663 npm2MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to turn music requests into traceable local DJ collections by scanning and indexing audio, planning tracklists, managing durable download jobs, and preparing hash-checked playlists, manifests, and experimental rekordbox exports for DJ app handoff.MIT