YouTube Playlist MCP

🇹🇷 Türkçe README

An MCP server that lets AI agents (Claude, ChatGPT, Cursor, …) research a topic on YouTube, rank the most valuable videos and save them as a playlist in your account.

Ask "I want to learn German, where should I start?" and get back a ready-to-watch playlist instead of 40 open tabs.

• 🔎 Searches 50–100 candidates, with filters for language, country, upload date and duration

• 📊 Scores every video 0–100 on popularity, like rate, comment rate and (optionally) recency, so an 8-year-old viral video doesn't win by age alone

• 🧹 Drops Shorts, live streams, low-view videos, and caps how many videos one channel can place in the list

• 🧠 Lets the agent judge relevance by reading titles and descriptions to remove off-topic, clickbait or wrong-language results

• 👀 Previews a numbered list (title, channel, duration, views, score) that you can tweak: "remove #3", "favour newer videos", "sort by like rate"

• ✅ Creates the playlist only after you approve it. Playlists are unlisted by default

• 🗂️ Manages your existing playlists: list them, add videos, remove videos

• 📉 Tracks the daily API quota and refuses up front if an action wouldn't fit

What it doesn't do: it doesn't watch or summarize videos, upload, comment, like, subscribe, or delete playlists, and it never scrapes. It only uses the official YouTube Data API v3.

Setup (about 10 minutes, one time)

Every user creates their own free Google Cloud project and OAuth client. You never share keys with the author or anyone else, your data and quota stay yours, and nothing passes through a third-party server.

0. Get the code

Requires Node.js 22 or newer and git.

git clone https://github.com/haktanonur/youtube-playlist-mcp.git
cd youtube-playlist-mcp
npm install
npm run build

To update later, run git pull && npm install && npm run build.

1. Create a Google Cloud project and enable the API

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

2. Open APIs & Services → Library, search for YouTube Data API v3 and click Enable.

2. Configure the OAuth consent screen

1. Go to APIs & Services → OAuth consent screen (shown as Google Auth Platform in newer consoles).

2. Choose External and fill in an app name and your email. ("Internal" is only offered to Google Workspace organizations. For a personal Gmail account, External is the only option. It doesn't make your app public: while it's in Testing mode, only the test users you add can sign in.)

3. Under Audience → Test users, add your own Google account (the one that owns the YouTube channel).

4. Under Data access, you can add the scope https://www.googleapis.com/auth/youtube (optional; the app asks for it anyway).

While the app's publishing status is Testing, Google expires the authorization after 7 days and you'll need to run auth again. To avoid that, click Publish app. Google will warn that the app is unverified, which is expected for a personal app only you use. You can click Advanced → Go to (app name).

3. Create an OAuth client

1. Go to APIs & Services → Credentials → Create credentials → OAuth client ID.

2. Application type: Desktop app.

3. Click Download JSON. You'll get a file like client_secret_XXXX.json.

4. Authorize (in a terminal, inside the project folder)

npm run auth -- --client-file ~/Downloads/client_secret_XXXX.json

A browser window opens. Sign in with your YouTube account and allow access. The client and token are saved to ~/.config/youtube-playlist-mcp/ (on Windows, %APPDATA%\youtube-playlist-mcp\) with permissions only you can read. After that you can delete the downloaded JSON.

5. Add it to your MCP client

You need two absolute paths: one to node (run which node, or where node on Windows) and one to dist/index.js in the folder you cloned.

Claude Desktop: edit claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "youtube-playlist": {
      "command": "/usr/local/bin/node",
      "args": ["/Users/you/youtube-playlist-mcp/dist/index.js"]
    }
  }
}

Use the full path to node: Claude Desktop doesn't always see your shell's PATH.

Claude Code:

claude mcp add youtube-playlist -- node /Users/you/youtube-playlist-mcp/dist/index.js

Cursor / VS Code / others: use the same command + args in the client's MCP config.

Restart the client and ask: "Build me a playlist of the best beginner Python tutorials in English, longer than 20 minutes."

Optional: search-only mode with an API key

If you only want search and scoring, without creating playlists, you can skip OAuth and use an API key (Credentials → Create credentials → API key, then restrict it to YouTube Data API v3):

"env": { "YOUTUBE_API_KEY": "your-key" }

Related MCP server: YouTube MCP Server

Tools

There is also a prompt, research_playlist, that walks the agent through the whole workflow.

Quota

Google gives each project 10,000 units per day for free (resets at midnight Pacific Time). A typical run looks like this: search 100 candidates (~202) + create a 20-video playlist (1,050) ≈ 1,250 units, so about 8 playlists a day. Writes are the expensive part: each video added costs 50 units. If your project has a higher quota, set YOUTUBE_DAILY_QUOTA.

The counter is kept locally, so it can't see usage from other apps that share the same Cloud project. YouTube's own "quota exceeded" error is still handled cleanly.

How scoring works

Each signal is converted to a percentile within the candidate pool, then combined with weights you can adjust:

Hidden likes or disabled comments count as neutral. Filters remove videos ≤60 s (or ≤3 min tagged #shorts), live/upcoming streams, videos under 1,000 views (min_views), and limit each channel to 2 videos (max_per_channel).

Configuration

CLI (from the project folder):

npm run status    # what is configured
npm run logout    # revoke access at Google and delete the token

Security & privacy

• Uses only the official YouTube Data API over HTTPS. There's no telemetry and no third-party server.

• OAuth uses the installed-app loopback flow with PKCE (S256) and a random state. The callback listens on 127.0.0.1 only and shuts down after one use or 5 minutes.

• Requests a single scope, youtube, which is the narrowest one that can manage playlists. The server has no tool that deletes playlists.

• Tokens and the OAuth client are stored in files with mode 0600, in a 0700 directory. Credentials are sent in headers, never in URLs.

• Every write tool requires confirm: true and is marked with MCP tool annotations. Each draft can only be created once, so a retry can't create duplicate playlists.

• Video titles and descriptions are treated as untrusted. Control and bidi characters are stripped, text is truncated, and the agent is told to treat it as data, not instructions.

• Revoke access at any time with logout or at https://myaccount.google.com/permissions.

See SECURITY.md for how to report vulnerabilities.

Development

npm test          # builds and runs unit + end-to-end tests (YouTube API is mocked)

Try it with the MCP Inspector:

npx @modelcontextprotocol/inspector node dist/index.js

License

MIT