YouTube Ultimate Toolkit MCP

<p align="center"> <img src="assets/banner.png" alt="YouTube Ultimate Toolkit MCP" width="100%"> </p>

<p align="center"> <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a> <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen" alt="Node.js"></a> <a href="https://github.com/Comzee/Youtube-Ultimate-Toolkit-MCP/stargazers"><img src="https://img.shields.io/github/stars/Comzee/Youtube-Ultimate-Toolkit-MCP" alt="GitHub stars"></a> <a href="https://github.com/Comzee/Youtube-Ultimate-Toolkit-MCP/commits/master"><img src="https://img.shields.io/github/last-commit/Comzee/Youtube-Ultimate-Toolkit-MCP" alt="GitHub last commit"></a> <a href="https://modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP-Compatible-blue" alt="MCP"></a> </p>

A powerful Model Context Protocol (MCP) server that gives Claude AI full access to YouTube content - transcripts, metadata, comments, screenshots, and audio clips.

Works with both Claude Desktop (local) and Claude Web UI (remote with OAuth).

Demo

Watch full demo video (MP4)

Why This MCP?

Feature	This MCP	Most Others
Transcripts	✅	✅
Timestamps	✅	Some
Time range filtering	✅	Rare
Transcript search	✅	Rare
Key segments (hook/outro)	✅	❌
Metadata	✅	✅
Playlists	✅	Some
Comments	✅	Very rare
Screenshots	✅	1-2 others
Audio clips	✅	❌
All URL formats	✅	Partial
OAuth 2.1 + PKCE	✅	❌
Password protection	✅	❌
Rate limiting	✅	❌
Claude Web UI support	✅	Few

Features

Tool	Description
get_video	Fetch video metadata and transcript with search, timestamps, and time ranges
get_playlist	List all videos in a playlist
get_comments	Get top comments with likes and reply counts
get_screenshot	Capture video frames at any timestamp
get_audio	Extract audio clips (max 120s) for speech/music analysis

Quick Start

Option 1: Local Mode (Claude Desktop)

# Install
git clone https://github.com/Comzee/Youtube-Ultimate-Toolkit-MCP.git
cd Youtube-Ultimate-Toolkit-MCP
npm install
npm run build

# Run
node dist/index.js

Add to Claude Desktop config (~/.config/claude/claude_desktop_config.json on Linux, ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "youtube": {
      "command": "node",
      "args": ["/path/to/Youtube-Ultimate-Toolkit-MCP/dist/index.js"]
    }
  }
}

Option 2: Remote Mode (Claude Web UI)

Remote mode requires OAuth setup and a public URL. See Remote Mode Setup below.

Prerequisites

• Node.js 18+
• yt-dlp - YouTube content fetcher (must be kept updated)
• ffmpeg - For screenshots and audio extraction (optional)
• YouTube API Key - For comments feature only (optional)

Installing Prerequisites

Ubuntu/Debian:

# Node.js 18+
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install -y nodejs

# yt-dlp (keep updated - YouTube breaks old versions frequently)
pip3 install --upgrade yt-dlp

# ffmpeg (for screenshots and audio)
sudo apt install ffmpeg

macOS:

brew install node yt-dlp ffmpeg

Windows:

# Install Node.js from https://nodejs.org
# Install yt-dlp: pip install yt-dlp
# Install ffmpeg from https://ffmpeg.org/download.html

Keeping yt-dlp Updated

YouTube frequently changes their API. If transcripts stop working, update yt-dlp:

pip3 install --upgrade yt-dlp
# or on systems that complain about externally-managed packages:
pip3 install --upgrade --break-system-packages yt-dlp

Installation

git clone https://github.com/Comzee/Youtube-Ultimate-Toolkit-MCP.git
cd Youtube-Ultimate-Toolkit-MCP
npm install
npm run build

Remote Mode Setup

Remote mode allows you to use this MCP with Claude Web UI (claude.ai) by exposing it over HTTPS with OAuth authentication.

1. Configure Environment

cp .env.example .env

Edit .env:

# OAuth credentials
OAUTH_CLIENT_ID=youtube-mcp-client
OAUTH_CLIENT_SECRET=your-secret-here  # Generate: openssl rand -hex 32

# Password for the consent page (bcrypt hash)
# Generate: node -e "require('bcrypt').hash('your-password', 12).then(console.log)"
AUTH_PASSWORD_HASH=$2b$12$...your-hash-here...

# Optional: YouTube API key for get_comments tool
YOUTUBE_API_KEY=your-api-key-here

2. Start the Server

# Development
npm run start:remote

# Production (with systemd)
sudo cp youtube-mcp.service /etc/systemd/system/
# Edit the service file to set your username and paths
sudo nano /etc/systemd/system/youtube-mcp.service
sudo systemctl daemon-reload
sudo systemctl enable youtube-mcp
sudo systemctl start youtube-mcp

3. Set Up HTTPS (Required)

Claude Web UI requires HTTPS. Use nginx as a reverse proxy:

server {
    listen 443 ssl;
    server_name your-domain.com;

    ssl_certificate /path/to/fullchain.pem;
    ssl_certificate_key /path/to/privkey.pem;

    location / {
        proxy_pass http://localhost:3010;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # WebSocket support
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        # Important for long-running requests
        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 86400s;
        proxy_send_timeout 86400s;
        proxy_set_header X-Accel-Buffering no;
    }
}

4. Connect Claude Web UI

1. Go to Settings → Connectors → Add Custom Connector
2. Enter URL: https://your-domain.com/mcp
3. Start a new chat and enable the MCP
4. Ask Claude to fetch a YouTube video - the authorization popup will appear
5. Enter your password on the consent page and click "Authorize"

Tools Reference

get_video

Fetches video metadata and English transcript.

Parameters:

Parameter	Required	Description
url	Yes	YouTube URL (any format) or video ID
includeTimestamps	No	Add [M:SS] timestamps to each line
startTime	No	Start time for transcript range (e.g., "60", "1:00")
endTime	No	End time for transcript range
searchTerm	No	Search transcript and highlight matches
keySegmentsOnly	No	Return only hook (first 40s) and outro (last 30s)

Supported URL formats:

• youtube.com/watch?v=VIDEO_ID
• youtu.be/VIDEO_ID
• youtube.com/shorts/VIDEO_ID
• youtube.com/live/VIDEO_ID
• youtube.com/embed/VIDEO_ID
• m.youtube.com/watch?v=VIDEO_ID
• music.youtube.com/watch?v=VIDEO_ID
• Direct video ID: dQw4w9WgXcQ

get_playlist

Lists videos in a YouTube playlist.

Parameters:

Parameter	Required	Description
url	Yes	YouTube playlist URL
limit	No	Max videos to return (default: 50, max: 200)

get_comments

Fetches top comments from a video. Requires YOUTUBE_API_KEY in .env.

Parameters:

Parameter	Required	Description
url	Yes	YouTube video URL or ID
maxResults	No	Number of comments (default: 25, max: 100)
order	No	Sort: "relevance" (default) or "time"

get_screenshot

Captures a frame from a video. Requires ffmpeg.

Parameters:

Parameter	Required	Description
url	Yes	YouTube video URL
timestamp	No	Time to capture (default: "0"). Formats: "30", "1:30", "1:30:00"

Returns: Base64-encoded JPEG image

get_audio

Extracts audio clips for analysis. Requires ffmpeg.

Parameters:

Parameter	Required	Description
url	Yes	YouTube video URL
startTime	No	Start time (default: "0")
endTime	No	End time (optional)
maxDuration	No	Max seconds (default: 60, max: 120)

Returns: Base64-encoded MP3 audio (128kbps)

OAuth & Security

The remote mode implements OAuth 2.1 with PKCE for secure authentication.

How It Works

1. Claude connects to /mcp - discovery/handshake methods work without auth
2. When you use a tool, Claude receives a 401 with OAuth discovery info
3. Claude performs dynamic client registration
4. Browser opens the consent page - you enter your password
5. Claude exchanges the auth code for an access token
6. Subsequent requests use the Bearer token

Security Features

Feature	Protection
Password-protected consent	Only you can authorize access
Bcrypt password hashing	Password stored securely
Rate limiting	5 attempts per IP, then 10-minute lockout
XSS protection	All OAuth parameters HTML-escaped
Command injection protection	yt-dlp spawned with shell: false
PKCE (S256)	Prevents authorization code interception

Troubleshooting

"No English transcript available"

Update yt-dlp - YouTube changes frequently:

pip3 install --upgrade yt-dlp

MCP won't connect from Claude Web UI

• Ensure HTTPS is configured correctly
• Check service status: sudo systemctl status youtube-mcp
• Check logs: sudo journalctl -u youtube-mcp -f

OAuth flow not starting

• Verify .well-known/ endpoints return 200 (not 401)
• Check browser console for CORS errors
• Ensure /register returns valid credentials

Authorization window doesn't appear

• OAuth triggers on first tool use, not on connection
• Start a chat, enable the MCP, then ask Claude to fetch a YouTube video

Claude using wrong/old tools

Disconnect and reconnect the MCP in Claude settings to refresh the tool list.

Claude Project Prompt

Use this prompt in a Claude Project to automatically leverage the MCP:

You have access to the YouTube MCP server. When I share a YouTube URL:
1. Automatically fetch the transcript with get_video
2. Provide a summary, key takeaways, and notable quotes
3. For long videos (10+ min), consider using keySegmentsOnly=true first

Available tools:
- get_video: Transcript and metadata (supports timestamps, time ranges, search)
- get_playlist: List videos in a playlist
- get_comments: Top comments (requires API key)
- get_screenshot: Capture frames at any timestamp
- get_audio: Extract audio clips for analysis (max 120s)

Architecture

• Transport: Streamable HTTP (MCP spec 2025-03-26)
• Sessions: Stateful with UUID identifiers (in-memory)
• OAuth: Authorization Code + PKCE, Dynamic Client Registration
• Tokens: In-memory storage (lost on restart)

License

MIT - See LICENSE for details.

Contributing

Contributions are welcome! Please open an issue or PR on GitHub.