# YouTube Transcript MCP Server

An MCP server that gives Claude access to YouTube video transcripts. Extract full transcripts, search for keywords with timestamps, and get direct YouTube links to matching moments.

## Tools

### `get_transcript`
Extract the full timestamped transcript from any YouTube video.

```
Title: Rick Astley - Never Gonna Give You Up (Official Video)
Channel: Rick Astley
Duration: 3:33
Source: captions | Language: en | Segments: 60
---
[0:01] [♪♪♪]
[0:18] ♪ We're no strangers to love ♪
[0:22] ♪ You know the rules and so do I ♪
...
```

### `search_transcript`
Keyword search across a video's transcript. Matches are grouped, marked with `>>>`, and include a YouTube link to jump to that moment.

```
Search: "give you up" in Rick Astley - Never Gonna Give You Up
Matches: 9 hits in 2 group(s)

--- Group 1 (1 hit(s)) — https://www.youtube.com/watch?v=dQw4w9WgXcQ&t=43 ---
     [0:40] ♪ Gotta make you understand ♪
 >>> [0:43] ♪ Never gonna give you up ♪
     [0:45] ♪ Never gonna let you down ♪
```

## Install

```bash
git clone https://github.com/yunlinwu/youtube-transcript-mcp.git
cd youtube-transcript-mcp
pip install -e .
```

For Whisper fallback (transcribes videos without captions):
```bash
pip install -e ".[whisper]"
```

## Setup

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "youtube-transcript": {
      "command": "/path/to/youtube-transcript-mcp/.venv/bin/youtube-transcript-mcp"
    }
  }
}
```

### Claude Code

Add to `.claude/settings.json`:

```json
{
  "mcpServers": {
    "youtube-transcript": {
      "command": "/path/to/youtube-transcript-mcp/.venv/bin/youtube-transcript-mcp"
    }
  }
}
```

Then restart Claude Desktop or Claude Code to pick up the server.

## How it works

1. You ask Claude about a YouTube video
2. Claude calls `get_transcript` or `search_transcript` via MCP
3. The server uses **yt-dlp** to fetch captions (or **Whisper** to transcribe audio as a fallback)
4. Claude gets back a compact, readable transcript and can summarize, search, or analyze it

## Requirements

- Python 3.10+
- [yt-dlp](https://github.com/yt-dlp/yt-dlp) (installed automatically)
- [FFmpeg](https://ffmpeg.org/) (only needed for Whisper fallback)

## Development

```bash
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest
```

## License

MIT