Content
# 🎬 yt-dlp-mcp
<div align="center">
**A powerful MCP server that brings video platform capabilities to your AI agents**
[](https://www.npmjs.com/package/@kevinwatt/yt-dlp-mcp)
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org/)
[](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>
