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
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
- Go to Settings → Connectors → Add Custom Connector
- Enter URL:
https://your-domain.com/mcp - Start a new chat and enable the MCP
- Ask Claude to fetch a YouTube video - the authorization popup will appear
- 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_IDyoutu.be/VIDEO_IDyoutube.com/shorts/VIDEO_IDyoutube.com/live/VIDEO_IDyoutube.com/embed/VIDEO_IDm.youtube.com/watch?v=VIDEO_IDmusic.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
- Claude connects to
/mcp- discovery/handshake methods work without auth - When you use a tool, Claude receives a 401 with OAuth discovery info
- Claude performs dynamic client registration
- Browser opens the consent page - you enter your password
- Claude exchanges the auth code for an access token
- 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
/registerreturns 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.