<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

![Demo](assets/demo.gif)

[Watch full demo video (MP4)](assets/demo.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)

```bash
# 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):

```json
{
  "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](#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:**
```bash
# 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:**
```bash
brew install node yt-dlp ffmpeg
```

**Windows:**
```bash
# 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:

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

## Installation

```bash
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

```bash
cp .env.example .env
```

Edit `.env`:

```bash
# 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

```bash
# 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:

```nginx
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:
```bash
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](LICENSE) for details.

## Contributing

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