Youtube-Ultimate-Toolkit-MCP

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?

Features

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:

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:

get_comments

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

Parameters:

get_screenshot

Captures a frame from a video. Requires ffmpeg.

Parameters:

Returns: Base64-encoded JPEG image

get_audio

Extracts audio clips for analysis. Requires ffmpeg.

Parameters:

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

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.