yt-music-mcp 0.1.1

MCP server for YouTube Music — lets AI agents search, browse, and manage your library via ytmusicapi.

yt-music-mcp

An MCP server that exposes YouTube Music to AI agents, via ytmusicapi.

Agents can search the catalog, browse artists/albums/songs, read the user's library and history, and create/edit/delete playlists, rate songs, and manage subscriptions.

---

Quickstart

You need two things in your config:

1. A way to run the server — recommended: uvx yt-music-mcp (no install needed, uv fetches it on first use).
2. Your YouTube Music auth — a one-time capture of request headers from music.youtube.com, stored either inline in the config or in a browser.json file.

1. Capture auth (one time, ~2-year validity)

Skip this if you only need public search/browsing.

1. Open https://music.youtube.com in a desktop browser, logged in.
2. Open DevTools (F12) → Network tab.
3. Click around to trigger traffic, then find any request to /youtubei/v1/....
4. Right-click that request → Copy → Copy request headers.

Then run one of:

# Option A — print the JSON to stdout so you can paste it into your config.
uvx yt-music-mcp setup-auth --stdout

# Option B — write a browser.json file you'll reference by path.
uvx yt-music-mcp setup-auth --out ~/.yt-music-mcp/browser.json

Paste your headers when prompted, then Ctrl-D (Ctrl-Z + Enter on Windows).

2. Configure your MCP client

Pick your client and paste one of the snippets below. Use the inline JSON variant if you used --stdout, or the file path variant if you used --out.

Claude Desktop

Config file:

OS	Path
Windows	%APPDATA%\Claude\claude_desktop_config.json
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

Inline JSON (recommended):

{
  "mcpServers": {
    "yt-music": {
      "command": "uvx",
      "args": ["yt-music-mcp"],
      "env": {
        "YTMUSIC_BROWSER_AUTH_JSON": "<paste the JSON from --stdout here>"
      }
    }
  }
}

File path:

{
  "mcpServers": {
    "yt-music": {
      "command": "uvx",
      "args": ["yt-music-mcp"],
      "env": {
        "YTMUSIC_BROWSER_AUTH": "C:\\Users\\you\\.yt-music-mcp\\browser.json"
      }
    }
  }
}

Heads up: Claude Desktop may not inherit your shell PATH. If uvx isn't found, use the absolute path (which uvx on macOS/Linux, where uvx on Windows).

Fully quit Claude Desktop (tray icon on Windows, ⌘-Q on macOS — closing the window isn't enough) and reopen. Click the 🔌 plug icon in any chat — you should see yt-music with 39 tools.

Claude Code

One command — pick the auth style that matches how you captured it:

# Inline JSON
claude mcp add yt-music -e YTMUSIC_BROWSER_AUTH_JSON="$(cat ~/.yt-music-mcp/browser.json)" -- uvx yt-music-mcp

# File path
claude mcp add yt-music -e YTMUSIC_BROWSER_AUTH=~/.yt-music-mcp/browser.json -- uvx yt-music-mcp

Scope the server to all projects or this one with -s user / -s project. Verify with claude mcp list, remove with claude mcp remove yt-music.

---

Try it

Once connected, ask Claude things like:

• Search & discovery
  • "Search YouTube Music for Radiohead albums."
  • "What are the global top 10 songs right now?"
  • "Find me some chill lo-fi playlists."
• Library (needs auth)
  • "Show my liked songs."
  • "What are the last 10 things I listened to?"
  • "Which artists am I subscribed to?"
• Playlist management (needs auth)
  • "Create a private playlist called 'Focus' and add these three songs: …"
  • "Add the top 5 tracks from the album OK Computer to my 'Road Trip' playlist."
  • "Remove the first track from my 'Focus' playlist."
  • "Like this song: "
• Composite flows
  • "Find me 20 songs similar to 'Weird Fishes/Arpeggi' and put them in a new playlist called 'Radiohead-ish'."
  • "Make a playlist from my top artists this month."

You'll see each tool call before it runs — review before approving anything that mutates your account.

---

Alternative installation

If you don't want uvx for some reason, you can also install via pipx:

pipx install yt-music-mcp

Then replace "command": "uvx", "args": ["yt-music-mcp"] with "command": "yt-music-mcp" in your config.

Or from source, for development:

git clone https://github.com/Thanaen/yt-music-mcp
cd yt-music-mcp
pip install -e ".[dev]"
pytest

---

Configuration reference

All configuration is via environment variables. Resolved in this order:

Variable	Purpose
YTMUSIC_BROWSER_AUTH_JSON	The full auth JSON as a string. Useful for keeping creds inline in a config file.
YTMUSIC_BROWSER_AUTH	Path to a browser.json file on disk.
(neither)	Unauthenticated mode — only public tools work.

If both are set, YTMUSIC_BROWSER_AUTH_JSON wins.

---

Tools reference

39 tools total. Unauthenticated tools work without any auth; authenticated ones need YTMUSIC_BROWSER_AUTH_JSON or YTMUSIC_BROWSER_AUTH.

Unauthenticated

Category	Tools
Search	search, get_search_suggestions
Browsing	get_artist, get_artist_albums, get_album, get_album_browse_id, get_song, get_song_related, get_lyrics, get_watch_playlist, get_user, get_user_playlists, get_user_videos
Explore	get_home, get_charts, get_mood_categories, get_mood_playlists, get_explore
Playlists (read)	get_playlist

Authenticated — reads

get_library_playlists, get_library_songs, get_library_albums, get_library_artists, get_library_subscriptions, get_liked_songs, get_history, get_account_info

Authenticated — mutations

• Playlists: create_playlist, edit_playlist, delete_playlist, add_playlist_items, remove_playlist_items
• Ratings: rate_song, rate_playlist
• Subscriptions: subscribe_artists, unsubscribe_artists
• History / library: add_history_item, remove_history_items, edit_song_library_status

⚠️ Mutations are always enabled. Agents can delete your playlists. Review each proposed tool call in the Claude UI before approving. For a read-only setup, just don't provide auth — mutation tools will then fail with an auth error.

---

Troubleshooting

Claude Desktop shows "server failed to start" uvx (or yt-music-mcp) isn't on Claude Desktop's PATH. Replace "command": "uvx" with the absolute path — e.g. C:\\Users\\you\\.local\\bin\\uvx.exe on Windows, or the output of which uvx on macOS/Linux.

"FileNotFoundError: YTMUSIC_BROWSER_AUTH does not point to a readable file" The env var's path is wrong. On Windows use \\ or forward slashes in JSON. Verify with:

python -c "import os,pathlib; print(pathlib.Path(os.environ['YTMUSIC_BROWSER_AUTH']).is_file())"

Library/playlist tools return "Please provide authentication" Your auth has expired or was captured from a logged-out session. Re-run uvx yt-music-mcp setup-auth ....

Nothing appears in Claude Desktop after editing the config Fully quit the app (tray icon / ⌘-Q — closing the window isn't enough), then reopen.

Check what the server sees Run it manually with the MCP Inspector:

npx @modelcontextprotocol/inspector uvx yt-music-mcp

---

Not in v1

• Uploads (upload_song, get_library_upload_*, …) — may land later.
• Podcasts (get_podcast, get_episode, …) — may land later.

License

MIT