This MCP server lets you search YouTube Music and manage playlists, history, and related listening data through natural-language tools.
Search music by query, with optional filters for songs, videos, albums, artists, playlists, community/featured playlists, profiles, podcasts, and episodes.
List your library playlists and fetch the tracks in any playlist.
Create private playlists, add tracks by video ID, remove tracks from playlists, and delete playlists you own (except the auto playlists LM/SE).
Read your recent YouTube Music play history.
Get a song's radio/autoplay queue and related-content sections for similarity signals.
Fetch lyrics and artist pages (top songs, albums, related artists).
Log out and revoke stored YouTube Music auth.
Allows searching YouTube Music, managing playlists, and reading listening history.
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., "@ytmusic-mcp search for 'Bohemian Rhapsody' on YouTube Music"
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.
An MCP server that wraps ytmusicapi so Claude (or any MCP client) can search YouTube Music, manage your playlists, and read your listening history.
Tool | Description |
| Search YouTube Music. |
| List your library playlists. Omit |
| Get the tracks in a playlist. Omit |
| Create a new private playlist, returns its ID. |
| Add a track to a playlist. |
| Remove every occurrence of a track from a playlist by video ID. |
| Permanently delete a playlist you own. Refuses to touch the auto playlists |
| Get your recent play history. |
| Get the radio/autoplay queue for a song — one of two independent similarity signals. |
| Get "related content" sections for a song (the |
| Get a song's lyrics (the |
| Get an artist's page: top songs, albums, related artists. |
| Delete the local auth file, revoking this server's stored YouTube Music authorization. |
Other Claude Code projects on this machine (e.g. re-com) call these tools by spawning this server over MCP rather than talking to ytmusicapi/YouTube Music themselves — this is the only place YouTube Music credentials live.
Not included (v1): BPM-based recommendations. YouTube Music doesn't expose tempo data, so this would need a second data source (e.g. an audio analysis API) — a stretch goal for a future version, not part of this build.
Related MCP server: mcp-server-youtube
python3 -m venv .venv
source .venv/bin/activate
pip install -e .There's no official YouTube Music API, so ytmusicapi authenticates by reusing headers from your logged-in browser session. Both methods below write the same headers_auth.json file, so you can switch between them freely.
Reads your existing YouTube Music session cookies straight from your browser's local storage — no DevTools, no copy-pasting.
pip install -e ".[browser-auth]"
python scripts/setup_auth_from_browser.py --browser firefox # or chrome, safari, edge, brave, opera, vivaldi, arcRequires being logged into music.youtube.com in that browser. Omit --browser to try every installed browser and use the first one with a valid session.
Notes:
Chrome/Edge/Brave/Opera/Vivaldi/Arc encrypt their cookie store; on macOS this may trigger a one-time Keychain permission prompt.
Some browsers lock their cookie database while running — close the browser first if extraction fails.
Use this if browser auto-extraction doesn't work for your setup.
Open music.youtube.com in Firefox (recommended — its raw-header copy is more reliable than Chrome's) while logged in.
Open DevTools (Cmd+Option+I / F12) → Network tab → filter by browse.
Click into a playlist, or reload the page, to trigger a browse POST request.
Click that request → Headers tab → toggle Raw headers → select and copy the whole block.
Paste it into a new file named raw_headers.txt in the project root and save.
Run:
python scripts/setup_auth_from_file.pyThis writes headers_auth.json and deletes raw_headers.txt.
Alternatively, python scripts/setup_auth.py does the same thing via an interactive terminal prompt instead of a file, if you prefer to paste directly.
headers_auth.json is equivalent to your logged-in session — never commit it or share it. It's already gitignored.
Verify auth works before going further:
python scripts/test_search.pyThese headers expire/rotate periodically. If tools start failing with an auth error, redo whichever setup option you used.
claude mcp add ytmusic -s user \
-e YTMUSIC_AUTH_PATH="$(pwd)/headers_auth.json" \
-- "$(pwd)/.venv/bin/python" "$(pwd)/server.py"-s user makes it available in any Claude Code session, not just this directory. Use absolute paths for the python interpreter, server.py, and YTMUSIC_AUTH_PATH since the server can be launched from any working directory.
For other MCP clients (Claude Desktop, etc.), point them at the same command and env var using their respective config format.
The unit test suite (tests/) runs against a hand-rolled fake YTMusic client — no network access or headers_auth.json needed:
pip install -e ".[dev]"
pytestscripts/test_search.py is a separate real-account smoke test, not part of the unit suite.
Tool calls translate common failure modes into clear messages instead of raw tracebacks:
Missing/expired/malformed auth → tells you to redo the authenticate step (scripts/setup_auth_from_browser.py or scripts/setup_auth_from_file.py).
Rate limiting (HTTP 429) → tells you to wait and retry.
Gated/restricted content → reported as unavailable rather than crashing.
Network errors → reported directly.
MIT — see LICENSE.
Add a track to a playlist by video ID.
Inputs: video_id (required), playlist_id (required). Returns: result
Create a new private playlist and return its playlist ID.
Inputs: name (required), description. Returns: result
Get recent play history.
Inputs: no named parameters. Returns: result
List your YouTube Music library playlists.
Inputs: no named parameters. Returns: result
Get the tracks in a playlist.
Inputs: playlist_id (required). Returns: result
Search YouTube Music.
filter: one of songs, videos, albums, artists, playlists, community_playlists, featured_playlists, profiles, podcasts, episodes. Omit for a mixed search. Returns an empty list if there are no matches.
Inputs: query (required), limit, filter. Returns: result
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 6 tools
Each tool targets a distinct action or resource: search, library playlists, playlist tracks, playlist creation, playlist modification, and history. No two tools have overlapping purposes, making selection unambiguous.
Tool names follow a consistent verb_noun pattern (search_music, get_playlists, get_playlist_tracks, create_playlist, add_to_playlist, get_history). The only minor deviation is 'add_to_playlist' instead of 'add_track_to_playlist', but the pattern is still clear.
With 6 tools, the number is well-scoped for a YouTube Music server that focuses on search, playlist management, and history. Each tool earns its place without being overwhelming or too sparse.
The set covers search, playlist CRUD (create, read tracks, add to), and history, but lacks tools for removing tracks from playlists, updating playlist metadata, or managing likes/ratings. This leaves some common music management workflows incomplete.
Search YouTube videos, read transcripts and get public video information in your AI assistant.
YouTube transcripts, search, channel browsing, and playlists for AI agents via MCP.
YouTube transcripts, search, channel/playlist listings and upload tracking for AI agents.
Fetch YouTube transcripts, monitor channels and track keyword matches from your AI assistant.
