yt-playlist-mcp

Local MCP server for Claude Desktop that searches YouTube and creates playlists on your own account.

Tools

• search_youtube(query, max_results) — video search with title, channel, duration, URL

• create_playlist(title, video_ids[], description?) — creates a private playlist and adds the videos in order

• search_playlists(query?) — lists your own playlists (optionally filtered by title substring) so later sessions can find one by ID

• add_to_playlist(playlist_id, video_ids[]) — appends videos to an existing playlist

• list_playlist_items(playlist_id) — lists a playlist's videos in order

• remove_video(playlist_id, video_id) — removes all occurrences of a video from a playlist

• reorder_playlist(playlist_id, video_ids[]) — puts the given videos first, in order; pass the full list to sort a whole playlist

• delete_playlist(playlist_id) — permanently deletes a whole playlist

Auth is OAuth 2.0 (Desktop-app client): a one-time browser consent flow stores a refresh token at ~/.config/yt-playlist-mcp/token.json (mode 600); after that the server refreshes access tokens silently.

1. Google Cloud setup (one time, in the browser)

1. Go to https://console.cloud.google.com/ and create a new project (e.g. yt-playlist-mcp).

2. Enable the API: APIs & Services → Library → search "YouTube Data API v3" → Enable.

3. OAuth consent screen: APIs & Services → OAuth consent screen (Google may call this "Google Auth Platform → Branding/Audience").

   • User type: External

   • App name / support email / developer email: anything (only you will see it)

   • Scopes: you can skip adding scopes here; the app requests https://www.googleapis.com/auth/youtube at runtime

   • Publish the app (Audience → "Publish app" → confirm "In production"). Leaving it in Testing status makes Google expire the refresh token every 7 days, forcing you to re-run the auth flow weekly. Published but unverified is fine for personal use — you'll click through one "Google hasn't verified this app" warning during consent (Advanced → "Go to yt-playlist-mcp (unsafe)").

4. Create credentials: APIs & Services → Credentials → Create credentials → OAuth client ID → Application type: Desktop app. Copy the Client ID and Client secret.

Related MCP server: Xiaozhi YouTube MCP

2. Build and authorize

npm install
npm run build
YOUTUBE_CLIENT_ID=xxx.apps.googleusercontent.com \
YOUTUBE_CLIENT_SECRET=yyy \
npm run auth

npm run auth opens your browser; sign in with the Google account whose YouTube you want to manage, click through the unverified-app warning, and approve. Tokens land in ~/.config/yt-playlist-mcp/token.json.

Re-run npm run auth any time to re-authorize (e.g. if you revoke access at https://myaccount.google.com/permissions).

3. Hook up Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (create it if missing) — use absolute paths, since Claude Desktop does not launch servers from this directory:

{
  "mcpServers": {
    "youtube": {
      "command": "/absolute/path/to/node",
      "args": ["/Users/will/Projects/youtube-mcp/dist/index.js"],
      "env": {
        "YOUTUBE_CLIENT_ID": "xxx.apps.googleusercontent.com",
        "YOUTUBE_CLIENT_SECRET": "yyy"
      }
    }
  }
}

(which node prints the node path.) Restart Claude Desktop; the two tools appear under the youtube server.

Quota

The YouTube Data API grants 10,000 units/day by default:

• search_youtube: ~101 units per call (search 100 + videos.list 1)

• create_playlist: 50 units + 50 per video added

• add_to_playlist: 50 units per video

• remove_video: ~51 units (lookup 1 + delete 50 per occurrence)

• search_playlists: 1 unit per 50 playlists

• list_playlist_items: 1 unit per 50 videos

• delete_playlist: ~51 units

• reorder_playlist: 50 units per video actually moved (already-in-place videos cost nothing)

So roughly 90 searches/day, or fewer if you create large playlists. Quota errors come back as tool errors mentioning quotaExceeded.

Development

npm run build   # tsc → dist/
npm start       # run the stdio server directly (for inspector/debugging)
npx @modelcontextprotocol/inspector node dist/index.js   # interactive test UI

Secrets never live in the repo: client ID/secret come from env vars (.env.example documents them), tokens live under ~/.config/yt-playlist-mcp/.