Overview

This MCP (Model Context Protocol) server provides an OAuth2-backed bridge between AI agents and the YouTube Data API so you can programmatically search for videos, create and manage playlists, and let AI curate collections on behalf of authenticated users. It exposes a small set of tools (MCP-compatible endpoints) that an LLM or agent can call to perform common playlist operations without embedding Google credentials inside the model.

Using an MCP server for playlist tasks keeps sensitive OAuth2 flows and tokens on a server you control, while letting models focus on decision-making (search queries, curation rules, playlist organization). It’s useful for building assistant workflows that can: assemble a playlist based on a prompt, extend a playlist with new search results, or produce categorized collections across multiple users.

Features

OAuth2 authorization with Google/YouTube for managing user playlists securely
Video search powered by the YouTube Data API
Create, update, and delete playlists on behalf of authenticated users
Add, reorder, and remove playlist items
Simple MCP tool endpoints designed for integration with LLMs and agent frameworks
Lightweight server that can be self-hosted and integrated into agent pipelines

Installation / Configuration

Clone the repository and install dependencies (Node.js/npm example):

git clone https://github.com/aardeshir/youtube-mcp.git
cd youtube-mcp
npm install

Create a Google Cloud OAuth 2.0 client (type: Web application) and configure the Authorized redirect URIs. Collect the Client ID and Client Secret.
Provide configuration via environment variables. Example .env:

# Google OAuth2
YT_CLIENT_ID=your-google-client-id.apps.googleusercontent.com
YT_CLIENT_SECRET=your-google-client-secret
REDIRECT_URI=https://your-domain.example.com/mcp/oauth/callback

# MCP server
MCP_PORT=3000
MCP_BASE_URL=https://your-domain.example.com

# (Optional) Persistence or session secret
SESSION_SECRET=some-long-random-value

Start the server:

npm start

Or with environment variables inline:

PORT=3000 YT_CLIENT_ID=... YT_CLIENT_SECRET=... npm start

Security notes:

Use HTTPS for production and ensure redirect URIs exactly match those configured in Google Cloud.
Store client secrets and refresh tokens securely (secrets manager or encrypted storage).
Validate OAuth state parameters and consider using PKCE for additional protection.

Available Resources

The server exposes a small set of MCP-compatible tools (HTTP endpoints). Below is a summary table of the commonly available endpoints and their purpose; consult the running server’s OpenAPI or /mcp/tools endpoint for exact signatures.

Endpoint	Method	Purpose
/mcp/oauth/authorize	GET	Redirects user to Google’s OAuth consent screen
/mcp/oauth/callback	GET	OAuth redirect handler; exchanges code for tokens
/mcp/tool/search_videos	POST	Search YouTube videos (query, maxResults)
/mcp/tool/create_playlist	POST	Create a new playlist (title, description, privacy)
/mcp/tool/add_to_playlist	POST	Add one or more videos to a playlist
/mcp/tool/get_playlists	GET	List user playlists
/mcp/tool/get_playlist_items	GET	Get items for a specific playlist
/mcp/tool/remove_item	DELETE	Remove an item from a playlist

Example: search_videos input and response (JSON):

Request (POST /mcp/tool/search_videos)

{
  "query": "lofi hip hop study beats",
  "maxResults": 5
}

Response

{
  "items": [
    {
      "videoId": "abc123",
      "title": "Lofi Hip Hop Radio - Beats to Study/Relax",
      "channelTitle": "Chillhop Music",
      "publishedAt": "2019-05-01T00:00:00Z"
    }
  ]
}

Use Cases

AI-curated study playlists: An assistant can ask a user for preferences, run several search_videos calls, filter results by duration/channel, and create a playlist with create_playlist followed by add_to_playlist calls.
Collaborative playlist building: Multiple authenticated users can authorize the MCP server separately; an AI agent aggregates recommendations from each account to produce a community list.
Topic-based discovery and export: Use search_videos with varied queries to assemble a themed set (e.g., “documentaries on climate change”), then programmatically export or share the playlist URL.
Content moderation workflows: An agent can scan playlist items, flag inappropriate videos, and remove items via remove_item.
Automated updates: Schedule periodic searches to add new content to evergreen playlists (e.g., daily news roundup).

Integration tips

Limit scopes to only those needed. For playlist management use:
- https://www.googleapis.com/auth/youtube (full access) or
- https://www.googleapis.com/auth/youtube.force-ssl (safer scope for playlist management)
Implement refresh-token handling so long-lived refresh tokens are used to obtain new access tokens without re-prompting users.
Return clear, typed responses from each tool so LLMs can parse results deterministically (IDs, titles, URLs).
Use rate limiting and backoff for YouTube Data API calls to avoid quota issues.

For the full source, examples, and any updates consult the GitHub repository: https://github.com/aardeshir/youtube-mcp.

YouTube MCP Server OAuth2 Playlist Builder