Youtube Music

A Python MCP server for managing YouTube Music playlists via Claude. Add and remove songs, create playlists, browse by mood, and ask Claude to suggest music — all through conversation. Changes sync to YouTube Music and show up on your phone, CarPlay, or wherever you listen.

Uses ytmusicapi as its backend, which talks directly to the YouTube Music internal API. This gives music-specific search (no music videos or compilations), mood/genre browsing, related song discovery, and direct access to your Liked Music.

What it does

Exposes 13 tools to Claude:

Tool	Description
list_playlists	List all your YouTube Music playlists
get_playlist_items	Get all songs in a playlist
create_playlist	Create a new playlist
update_playlist	Rename or update a playlist's description
delete_playlist	Delete a playlist
search_songs	Search for songs — music tracks only, no videos or compilations
add_song_to_playlist	Add a confirmed song by video ID
remove_song_from_playlist	Remove a song from a playlist
refresh_playlists	Force a full sync from YouTube Music
get_liked_songs	Get your Liked Music directly
get_mood_categories	Browse available mood/genre categories
get_mood_playlists	Get curated playlists for a mood category
get_song_related	Find songs related to a given track

All playlist tools accept "liked" as a shorthand for your Liked Music playlist.

Prerequisites

• Python 3.10+
• A Google account with YouTube Music

Setup

git clone https://github.com/dustinbarnes/youtube-music-mcp
cd youtube-music-mcp
pip install -e .

Authenticate

Run the one-time OAuth setup:

youtube-music-mcp --setup

This opens your browser to a Google sign-in page. After approving access, a token is saved to ~/.config/youtube-music-mcp/oauth.json and reused automatically. You won't need to do this again unless you revoke access or delete the file.

Never commit oauth.json or cache.db to version control. Both are in .gitignore.

Claude Desktop

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "youtube-music": {
      "command": "/path/to/youtube-music-mcp/.venv/bin/youtube-music-mcp"
    }
  }
}

Or if you installed globally with pip install -e .:

{
  "mcpServers": {
    "youtube-music": {
      "command": "youtube-music-mcp"
    }
  }
}

Claude Code

claude mcp add youtube-music -- youtube-music-mcp

Or with a venv:

claude mcp add youtube-music -- /path/to/youtube-music-mcp/.venv/bin/youtube-music-mcp

Usage examples

Once connected, talk to Claude naturally:

• "What playlists do I have?"
• "Search for Phoebe Bridgers Garden Song"
• "Add something upbeat and driving to my CarPlay playlist"
• "What are the mood categories available?"
• "Show me chill playlists"
• "What songs are related to Fleetwood Mac - The Chain?"
• "Create a new playlist called Road Trip"
• "Remove the second song from my Workout playlist"
• "Sync my playlists — I made changes on my phone"

Claude uses search_songs to find music-specific results (no music videos or hour-long compilations) and presents them to you before adding anything.

Local data

The server keeps a SQLite cache at ~/.config/youtube-music-mcp/cache.db to reduce API calls. Playlist contents update automatically when you make changes through Claude. Search results are cached for one hour. Use refresh_playlists to pull in changes made from other devices or apps.

Development

pip install -e ".[dev]"
pytest                 # run tests
pytest -v              # verbose

Contributing

Pull requests welcome. All contributions require review. Please include tests for new behavior and clear commit messages.

License

MIT