# 🎬 yt-dlp-mcp

<div align="center">

**A powerful MCP server that brings video platform capabilities to your AI agents**

[![npm version](https://img.shields.io/npm/v/@kevinwatt/yt-dlp-mcp.svg)](https://www.npmjs.com/package/@kevinwatt/yt-dlp-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.6-blue)](https://www.typescriptlang.org/)

Integrate yt-dlp with Claude, Dive, and other MCP-compatible AI systems. Download videos, extract metadata, get transcripts, and more — all through natural language.

[Features](#-features) • [Installation](#-installation) • [Tools](#-available-tools) • [Usage](#-usage-examples) • [Documentation](#-documentation)

</div>

---

## ✨ Features

<table>
<tr>
<td width="50%">

### 🔍 **Search & Discovery**
- Search YouTube with pagination
- JSON or Markdown output formats
- Filter by relevance and quality

### 📊 **Metadata Extraction**
- Comprehensive video information
- Channel details and statistics
- Upload dates, tags, categories
- No content download required

### 📝 **Transcript & Subtitles**
- Download subtitles in VTT format
- Generate clean text transcripts
- Multi-language support
- Auto-generated captions

</td>
<td width="50%">

### 🎥 **Video Downloads**
- Resolution control (480p-1080p)
- Video trimming support
- Platform-agnostic (YouTube, Facebook, etc.)
- Saved to Downloads folder

### 🎵 **Audio Extraction**
- Best quality audio (M4A/MP3)
- Direct audio-only downloads
- Perfect for podcasts & music

### 🛡️ **Privacy & Safety**
- No tracking or analytics
- Direct downloads via yt-dlp
- Zod schema validation
- Character limits for LLM safety

</td>
</tr>
</table>

---

## 🚀 Installation

### Prerequisites

**Install yt-dlp** on your system:

<table>
<tr>
<th>Platform</th>
<th>Command</th>
</tr>
<tr>
<td>🪟 <strong>Windows</strong></td>
<td><code>winget install yt-dlp</code></td>
</tr>
<tr>
<td>🍎 <strong>macOS</strong></td>
<td><code>brew install yt-dlp</code></td>
</tr>
<tr>
<td>🐧 <strong>Linux</strong></td>
<td><code>pip install yt-dlp</code></td>
</tr>
</table>

### Getting Started

Add the following config to your MCP client:

```json
{
  "mcpServers": {
    "yt-dlp": {
      "command": "npx",
      "args": ["-y", "@kevinwatt/yt-dlp-mcp@latest"]
    }
  }
}
```

### MCP Client Configuration

<details open>
<summary><strong>Dive</strong></summary>

1. Open [Dive Desktop](https://github.com/OpenAgentPlatform/Dive)
2. Click **"+ Add MCP Server"**
3. Paste the config provided above
4. Click **"Save"** and you're ready!

</details>

<details>
<summary><strong>Claude Code</strong></summary>

Use the Claude Code CLI to add the yt-dlp MCP server ([guide](https://docs.anthropic.com/en/docs/claude-code/mcp)):

```bash
claude mcp add yt-dlp npx @kevinwatt/yt-dlp-mcp@latest
```

</details>

<details>
<summary><strong>Claude Desktop</strong></summary>

Add to your `claude_desktop_config.json`:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "yt-dlp": {
      "command": "npx",
      "args": ["-y", "@kevinwatt/yt-dlp-mcp@latest"]
    }
  }
}
```

</details>

<details>
<summary><strong>Cursor</strong></summary>

Go to `Cursor Settings` -> `MCP` -> `New MCP Server`. Use the config provided above.

</details>

<details>
<summary><strong>VS Code / Copilot</strong></summary>

Install via the VS Code CLI:

```bash
code --add-mcp '{"name":"yt-dlp","command":"npx","args":["-y","@kevinwatt/yt-dlp-mcp@latest"]}'
```

Or follow the [MCP install guide](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server) with the standard config from above.

</details>

<details>
<summary><strong>Windsurf</strong></summary>

Follow the [configure MCP guide](https://docs.windsurf.com/windsurf/cascade/mcp#mcp-config-json) using the standard config from above.

</details>

<details>
<summary><strong>Cline</strong></summary>

Follow [Cline MCP configuration guide](https://docs.cline.bot/mcp/configuring-mcp-servers) and use the config provided above.

</details>

<details>
<summary><strong>Warp</strong></summary>

Go to `Settings | AI | Manage MCP Servers` -> `+ Add` to [add an MCP Server](https://docs.warp.dev/knowledge-and-collaboration/mcp#adding-an-mcp-server). Use the config provided above.

</details>

<details>
<summary><strong>JetBrains AI Assistant</strong></summary>

Go to `Settings | Tools | AI Assistant | Model Context Protocol (MCP)` -> `Add`. Use the config provided above.

</details>

### Manual Installation

```bash
npm install -g @kevinwatt/yt-dlp-mcp
```

---

## 🛠️ Available Tools

All tools are prefixed with `ytdlp_` to avoid naming conflicts with other MCP servers.

### 🔍 Search & Discovery

<table>
<tr>
<th width="30%">Tool</th>
<th width="70%">Description</th>
</tr>
<tr>
<td><code>ytdlp_search_videos</code></td>
<td>

Search YouTube with pagination and date filtering support
- **Parameters**: `query`, `maxResults`, `offset`, `response_format`, `uploadDateFilter`
- **Date Filter**: `hour`, `today`, `week`, `month`, `year` (optional)
- **Returns**: Video list with titles, channels, durations, URLs
- **Supports**: JSON and Markdown formats

</td>
</tr>
</table>

### 📝 Subtitles & Transcripts

<table>
<tr>
<th width="30%">Tool</th>
<th width="70%">Description</th>
</tr>
<tr>
<td><code>ytdlp_list_subtitle_languages</code></td>
<td>

List all available subtitle languages for a video
- **Parameters**: `url`
- **Returns**: Available languages, formats, auto-generated status

</td>
</tr>
<tr>
<td><code>ytdlp_download_video_subtitles</code></td>
<td>

Download subtitles in VTT format with timestamps
- **Parameters**: `url`, `language` (optional)
- **Returns**: Raw VTT subtitle content

</td>
</tr>
<tr>
<td><code>ytdlp_download_transcript</code></td>
<td>

Generate clean plain text transcript
- **Parameters**: `url`, `language` (optional)
- **Returns**: Cleaned text without timestamps or formatting

</td>
</tr>
</table>

### 🎥 Video & Audio Downloads

<table>
<tr>
<th width="30%">Tool</th>
<th width="70%">Description</th>
</tr>
<tr>
<td><code>ytdlp_download_video</code></td>
<td>

Download video to Downloads folder
- **Parameters**: `url`, `resolution`, `startTime`, `endTime`
- **Resolutions**: 480p, 720p, 1080p, best
- **Supports**: Video trimming

</td>
</tr>
<tr>
<td><code>ytdlp_download_audio</code></td>
<td>

Extract and download audio only
- **Parameters**: `url`
- **Format**: Best quality M4A/MP3

</td>
</tr>
</table>

### 📊 Metadata

<table>
<tr>
<th width="30%">Tool</th>
<th width="70%">Description</th>
</tr>
<tr>
<td><code>ytdlp_get_video_metadata</code></td>
<td>

Extract comprehensive video metadata in JSON
- **Parameters**: `url`, `fields` (optional array)
- **Returns**: Complete metadata or filtered fields
- **Includes**: Views, likes, upload date, tags, formats, etc.

</td>
</tr>
<tr>
<td><code>ytdlp_get_video_metadata_summary</code></td>
<td>

Get human-readable metadata summary
- **Parameters**: `url`
- **Returns**: Formatted text with key information

</td>
</tr>
</table>

### 💬 Comments

<table>
<tr>
<th width="30%">Tool</th>
<th width="70%">Description</th>
</tr>
<tr>
<td><code>ytdlp_get_video_comments</code></td>
<td>

Extract comments in flat JSON, threaded JSON, or AI-friendly Markdown
- **Parameters**: `url`, `maxComments`, `sortOrder`, `view`, `responseFormat`, `maxParents`, `maxReplies`, `maxRepliesPerThread`, `maxDepth`
- **Views**: `flat` (default) or `threaded`
- **Formats**: `json` (default) or `markdown_tree` (`markdown_tree` requires threaded view)
- **Returns**: Comment objects with `depth`, `reply_count`, `root_threads`, `reply_comments`, `orphan_comments`
- **Graceful Degradation**: On platforms without parent metadata, threaded mode falls back to root-only comments

</td>
</tr>
<tr>
<td><code>ytdlp_get_video_comments_summary</code></td>
<td>

Get a human-readable summary of comments
- **Parameters**: `url`, `maxComments`, `view`
- **Views**: `flat` (linear summary) or `threaded` (grouped reply trees)
- **Returns**: Readable comment digest with author badges, time, likes, and grouped replies

</td>
</tr>
</table>

---

## 💡 Usage Examples

### Search Videos

```
"Search for Python programming tutorials"
"Find the top 20 machine learning videos"
"Search for 'react hooks tutorial' and show results 10-20"
"Search for JavaScript courses in JSON format"
```

### Get Metadata

```
"Get metadata for https://youtube.com/watch?v=..."
"Show me the title, channel, and view count for this video"
"Extract just the duration and upload date"
"Give me a quick summary of this video's info"
```

### Get Comments

```
"Get the top 20 comments for https://youtube.com/watch?v=..."
"Get comments as threaded JSON for this video"
"Extract comments as markdown_tree so the reply branches stay intact"
"Get newest comments with maxDepth 1 and maxRepliesPerThread 0"
"Summarize comments in threaded view"
```

### Download Subtitles & Transcripts

```
"List available subtitles for https://youtube.com/watch?v=..."
"Download English subtitles from this video"
"Get a clean transcript of this video in Spanish"
"Download Chinese (zh-Hant) transcript"
```

### Download Content

```
"Download this video in 1080p: https://youtube.com/watch?v=..."
"Download audio from this YouTube video"
"Download this video from 1:30 to 2:45"
"Save this Facebook video to my Downloads"
```

---

## 📖 Documentation

- **[API Reference](./docs/api.md)** - Detailed tool documentation
- **[Configuration](./docs/configuration.md)** - Environment variables and settings
- **[Cookie Configuration](./docs/cookies.md)** - Authentication and private video access
- **[Error Handling](./docs/error-handling.md)** - Common errors and solutions
- **[Contributing](./docs/contributing.md)** - How to contribute

---

## 🔧 Configuration

### Environment Variables

```bash
# Downloads directory (default: ~/Downloads)
YTDLP_DOWNLOADS_DIR=/path/to/downloads

# Default resolution (default: 720p)
YTDLP_DEFAULT_RESOLUTION=1080p

# Default subtitle language (default: en)
YTDLP_DEFAULT_SUBTITLE_LANG=en
```

See the [Configuration Guide](./docs/configuration.md) for the full list.

### Proxy and yt-dlp Config File

All tools read your yt-dlp config file (`~/.config/yt-dlp/config`), so any
`--proxy`, `--cookies` or other options set there apply automatically. This is
the only channel available to MCP clients that cannot pass environment
variables to the server process.

These are alternatives — set only the one you need:

| Setting | Effect |
|---------|--------|
| `YTDLP_PROXY=socks5://127.0.0.1:1080` | Route all requests through this proxy |
| `YTDLP_PROXY=` (empty) | Force a direct connection, overriding a proxy in the yt-dlp config file |
| `YTDLP_IGNORE_CONFIG=1` | Skip all yt-dlp config files |

Supported proxy schemes: `http`, `https`, `socks4`, `socks5`, `socks5h`.

> `YTDLP_IGNORE_CONFIG=1` is not a straight revert to 0.9.x. The search,
> metadata and comments tools always read the config file, so this setting
> stops them from doing so as well.

**MCP Configuration with a proxy:**

```json
{
  "mcpServers": {
    "yt-dlp": {
      "command": "npx",
      "args": ["-y", "@kevinwatt/yt-dlp-mcp@latest"],
      "env": {
        "YTDLP_PROXY": "socks5://127.0.0.1:1080"
      }
    }
  }
}
```

If your MCP client cannot pass environment variables to the server, put the
options in `~/.config/yt-dlp/config` instead — every tool reads that file:

```
--proxy socks5://127.0.0.1:1080
--cookies /path/to/cookies.txt
```

> **Note**: Your config file applies to downloads as well. Options that change
> the output format (`-x`, `--remux-video`, `--recode-video`) change what the
> download tools produce; the tools report the file yt-dlp actually wrote, so
> the reported name stays correct. Output-location options (`-o`, `-P`) have no
> effect, because the tools always pass an absolute `--output` on the command
> line, which takes precedence.
>
> **Note**: yt-dlp config files can contain options that execute commands
> (`--exec`, `--postprocessor-args`, `--ffmpeg-location`). These now run on
> tool invocations too, including ones triggered by an AI assistant. Set
> `YTDLP_IGNORE_CONFIG=1` if you would rather the server ignore your config
> file entirely.

### Cookie Configuration

To access private videos, age-restricted content, or avoid rate limits, configure cookies:

> ⚠️ **Important**: Cookie authentication requires a JavaScript runtime (deno) to be installed. When using cookies, YouTube uses authenticated API endpoints that require JavaScript challenge solving. Without deno, downloads will fail with "n challenge solving failed" error.
>
> Install deno: https://docs.deno.com/runtime/getting_started/installation/

```bash
# Extract cookies from browser (recommended)
YTDLP_COOKIES_FROM_BROWSER=chrome

# Or use a cookie file
YTDLP_COOKIES_FILE=/path/to/cookies.txt
```

**MCP Configuration with cookies:**

```json
{
  "mcpServers": {
    "yt-dlp": {
      "command": "npx",
      "args": ["-y", "@kevinwatt/yt-dlp-mcp@latest"],
      "env": {
        "YTDLP_COOKIES_FROM_BROWSER": "chrome"
      }
    }
  }
}
```

Supported browsers: `brave`, `chrome`, `chromium`, `edge`, `firefox`, `opera`, `safari`, `vivaldi`, `whale`

See [Cookie Configuration Guide](./docs/cookies.md) for detailed setup instructions.

---

## 🏗️ Architecture

### Built With

- **[yt-dlp](https://github.com/yt-dlp/yt-dlp)** - Video extraction engine
- **[MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk)** - Model Context Protocol
- **[Zod](https://github.com/colinhacks/zod)** - TypeScript-first schema validation
- **TypeScript** - Type safety and developer experience

### Key Features

- ✅ **Type-Safe**: Full TypeScript with strict mode
- ✅ **Validated Inputs**: Zod schemas for runtime validation
- ✅ **Character Limits**: Automatic truncation to prevent context overflow
- ✅ **Tool Annotations**: readOnly, destructive, idempotent hints
- ✅ **Error Guidance**: Actionable error messages for LLMs
- ✅ **Modular Design**: Clean separation of concerns

---

## 📊 Response Formats

### JSON Format
Perfect for programmatic processing:
```json
{
  "total": 50,
  "count": 10,
  "offset": 0,
  "videos": [...],
  "has_more": true,
  "next_offset": 10
}
```

### Markdown Format
Human-readable display:
```markdown
Found 50 videos (showing 10):

1. **Video Title**
   📺 Channel: Creator Name
   ⏱️  Duration: 10:30
   🔗 URL: https://...
```

### Comment Markdown Tree
Useful for LLM analysis when reply context matters:
```markdown
# AI-Ready Comment Threads

source_title: "Sample Video"
comments_detected: 20
root_threads: 6
reply_comments: 14

## Threads

### Thread 1

- comment_id: "abc123"
  parent_id: "root"
  depth: 0
  reply_count: 2
  text:
    | Root comment text
  - comment_id: "reply456"
    parent_id: "abc123"
    depth: 1
    reply_count: 0
    text:
      | Reply text
```

### Comment Limits
YouTube comment extraction supports the full extractor tuple:
```text
youtube:comment_sort=<sort>;max_comments=<total>,<parents>,<replies>,<repliesPerThread>,<depth>
```

Examples:
- Default behavior: `maxComments=20` yields `max_comments=20,20,20,20,2`
- Root-only comments: `maxDepth=1`, `maxRepliesPerThread=0`
- Limited branching: `maxReplies=40`, `maxRepliesPerThread=5`, `maxDepth=2`

---

## 🔒 Privacy & Security

- **No Tracking**: Direct downloads, no analytics
- **Input Validation**: Zod schemas prevent injection
- **URL Validation**: Strict URL format checking
- **Character Limits**: Prevents context overflow attacks
- **Read-Only by Default**: Most tools don't modify system state

---

## 🤝 Contributing

Contributions are welcome! Please check out our [Contributing Guide](./docs/contributing.md).

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

---

## 📝 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

## 🙏 Acknowledgments

- [yt-dlp](https://github.com/yt-dlp/yt-dlp) - The amazing video extraction tool
- [Anthropic](https://www.anthropic.com/) - For the Model Context Protocol
- [Dive](https://github.com/OpenAgentPlatform/Dive) - MCP-compatible AI platform

---

## 📚 Related Projects

- [MCP Servers](https://github.com/modelcontextprotocol/servers) - Official MCP server implementations
- [yt-dlp](https://github.com/yt-dlp/yt-dlp) - Command-line video downloader
- [Dive Desktop](https://github.com/OpenAgentPlatform/Dive) - AI agent platform

---

<div align="center">

[⬆ Back to Top](#-yt-dlp-mcp)

</div>