yt-dj-mcp

Local YouTube Music DJ crate MCP server.

The server syncs liked songs from YouTube Music, stores approximate DJ metadata such as BPM, key, Camelot key, and genre, then creates playlists only from saved previews.

Who This Is For

Use this if you have a large YouTube Music liked-song library and want a local, agent-friendly way to turn it into DJ crates. The workflow is deliberately preview-first: inspect candidates locally, then create playlists only after you approve a saved preview.

What It Can Do

• Sync YouTube Music liked songs into local SQLite.
• Analyze short local audio sections with yt-dlp, ffmpeg, and Essentia.
• Store BPM, musical key, Camelot key, confidence, and source.
• Search tracks by BPM/key/genre.
• Save playlist previews before writing to YouTube Music.
• Create YouTube Music playlists from reviewed previews.

Safety

• Uses OAuth by default.
• Stores secrets in ~/.config/yt-dj-mcp/.
• Never prints credential file contents.
• Creates playlists only from saved previews.
• Browser/HAR auth is an explicit fallback and stores session headers in browser.json; keep it local and never commit it.
• Runtime state is local-only. Do not publish library.sqlite, HAR files, browser headers, OAuth tokens, or downloaded audio.

Quick Start

git clone https://github.com/YOUR_USERNAME/yt-dj-mcp.git
cd yt-dj-mcp
python -m venv .venv
. .venv/bin/activate
pip install -e ".[dev,audio]"
pytest -q

Add the MCP server to your client:

[mcp_servers.yt_dj_mcp]
command = "/absolute/path/to/yt-dj-mcp/.venv/bin/yt-dj-mcp"
args = ["serve"]

OAuth Setup

Create a Google Cloud OAuth client that can be used by ytmusicapi, then run:

yt-dj-mcp setup-auth
yt-dj-mcp auth-status

If OAuth token creation succeeds but YouTube Music requests return HTTP 400, use the explicit local browser fallback:

ytmusicapi browser --file ~/.config/yt-dj-mcp/browser.json
chmod 600 ~/.config/yt-dj-mcp/browser.json
yt-dj-mcp auth-status

If copying request headers from DevTools is unreliable, export a Chrome Network HAR and import it:

yt-dj-mcp import-har /path/to/music.youtube.com.har
yt-dj-mcp auth-status

browser.json contains browser session headers. Keep it local and never commit it.

Commands

yt-dj-mcp setup-auth
yt-dj-mcp auth-status
yt-dj-mcp import-har /path/to/music.youtube.com.har
yt-dj-mcp enrich-tracks --limit 25
yt-dj-mcp reset-auth
yt-dj-mcp serve

MCP tools exposed by the server:

• auth_status
• setup_auth_instructions
• sync_liked_songs
• list_liked_songs
• enrich_tracks
• find_dj_candidates
• create_playlist_preview
• get_playlist_preview
• create_youtube_music_playlist
• update_track_metadata

Audio Metadata Enrichment

enrich-tracks fills missing BPM/key/Camelot metadata by downloading a short audio section with yt-dlp, analyzing it with Essentia, then caching the analysis under ~/.config/yt-dj-mcp/audio-metadata-cache/.

Required local commands/packages:

ffmpeg -version
python -m yt_dlp --version
python -c "import essentia; print(essentia.__version__)"

The command is best run in small batches:

yt-dj-mcp enrich-tracks --limit 10
yt-dj-mcp enrich-tracks --limit 50

If yt-dlp or Essentia is missing, enrichment will leave tracks in the missing count instead of crashing the server. Use this only for music you are allowed to process locally; downloading streamed audio may be restricted by the service's terms.

First Crate Workflow

1. Run yt-dj-mcp setup-auth.
2. Run yt-dj-mcp auth-status.
3. Add the MCP server to Codex or Claude.
4. Call sync_liked_songs.
5. Run yt-dj-mcp enrich-tracks --limit 25 or call MCP enrich_tracks.
6. Call find_dj_candidates.
7. Call create_playlist_preview.
8. Review with get_playlist_preview.
9. Create the YouTube Music playlist with create_youtube_music_playlist.

Suggested Agent Prompt

After installing the MCP server, try:

Sync my YouTube Music liked songs, enrich 50 tracks with BPM/key metadata, then
create 12-track DJ playlist previews grouped by compatible BPM and Camelot key.

Review previews before asking the agent to create real YouTube Music playlists.

Limitations

• BPM/key values are estimates. Use your ears before playing out.
• YouTube Music auth can be brittle. OAuth is preferred, while browser/HAR auth is a local fallback when OAuth does not work.
• Audio analysis depends on ffmpeg, yt-dlp, and Essentia availability.
• This project does not manage playback and does not provide destructive library operations.

License

MIT