youtube-playlist-manager

An MCP (Model Context Protocol) server that lets Claude and other AI assistants manage your YouTube playlists. Includes a React GUI accessible via a browser.

Features

• List, search, create, update and delete playlists
• Add and remove videos from playlists
• Get video details
• React-based GUI for visual management
• OAuth2 authentication with automatic token refresh

Prerequisites

• Node.js >= 18
• A Google Cloud project with the YouTube Data API v3 enabled
• OAuth 2.0 credentials (Client ID + Client Secret) — the redirect URI depends on your setup (see step 3)

Installation & Setup

1. Create your config file

Create the directory ~/.config/youtube-playlist-manager/ and add a .env file:

GOOGLE_CLIENT_ID=your_client_id_here
GOOGLE_CLIENT_SECRET=your_client_secret_here

# Optional
GUI_PORT=3001
PROXY_URL=http://localhost:3000
PROXY_APP_PATH=/youtube-playlist-manager
PROXY_APP_NAME=YouTube Playlist Manager

# Docker / custom redirect URI (overrides PROXY_URL+PROXY_APP_PATH)
# OAUTH_CALLBACK_BASE_URL=http://localhost:8080/youtube-playlist-manager

The redirect URI sent to Google is built with the following priority:

| Scenario | redirect_uri | |---|---| | OAUTH_CALLBACK_BASE_URL set | {OAUTH_CALLBACK_BASE_URL}/oauth2callback | | PROXY_URL + PROXY_APP_PATH set | {PROXY_URL}{PROXY_APP_PATH}/oauth2callback | | Default | http://localhost:{GUI_PORT}/oauth2callback |

Declare the corresponding URL as an Authorized redirect URI in the Google Cloud Console.

Windows: ~ refers to C:\Users\<YourName>\.config\youtube-playlist-manager\.env

2. Authenticate with YouTube

npx youtube-playlist-manager-setup

This opens a browser OAuth flow and saves your tokens to ~/.config/youtube-playlist-manager/tokens.json.

3. Configure your MCP client (Claude Desktop / Cursor)

Add the following to your MCP config:

{
  "mcpServers": {
    "youtube-playlist-manager": {
      "command": "npx",
      "args": ["-y", "youtube-playlist-manager"],
      "env": {
        "GOOGLE_CLIENT_ID": "your_client_id_here",
        "GOOGLE_CLIENT_SECRET": "your_client_secret_here",
        "GUI_PORT": "3001",
        "OAUTH_CALLBACK_BASE_URL": "http://localhost:3001"
      }
    }
  }
}

Note: The env block is an alternative to the .env file. If both are present, the .env file takes precedence (the server loads it with override: true, which overwrites process.env).

Available Tools

| Tool | Description | |---|---| | list_playlists | List all your YouTube playlists | | search_playlists | Search playlists by title | | get_playlist_items | Get videos inside a playlist | | get_video_details | Get details of a specific video | | add_video_to_playlist | Add a video to a playlist | | remove_video_from_playlist | Remove a video from a playlist | | create_playlist | Create a new playlist | | update_playlist | Update title, description or privacy | | delete_playlist | Permanently delete a playlist |

Config directory

All user data is stored in ~/.config/youtube-playlist-manager/:

| File | Purpose | |---|---| | .env | Your Google OAuth credentials | | tokens.json | OAuth tokens (auto-managed) |

Development

git clone https://github.com/your-username/youtube-playlist-manager
cd youtube-playlist-manager
npm install
npm run install:gui
npm run build

License

ISC