🎬 yt-dlp-mcp
A powerful MCP server that brings video platform capabilities to your AI agents
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
🔍 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
- Auto-generated captions
🎥 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
🚀 Installation
Prerequisites
Install yt-dlp on your system:
Platform
Command
🪟 Windows
winget install yt-dlp
🍎 macOS
brew install yt-dlp
🐧 Linux
pip install yt-dlp
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
Dive
1. Open Dive Desktop
2. Click **"+ Add MCP Server"**
3. Paste the config provided above
4. Click **"Save"** and you're ready!
Claude Code
Use the Claude Code CLI to add the yt-dlp MCP server (guide):```bash
claude mcp add yt-dlp npx @kevinwatt/yt-dlp-mcp@latest
Claude Desktop
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"]
}
}
}
Cursor
Go to `Cursor Settings` -> `MCP` -> `New MCP Server`. Use the config provided above.
VS Code / Copilot
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 with the standard config from above.
Windsurf
Follow the configure MCP guide using the standard config from above.
Cline
Follow Cline MCP configuration guide and use the config provided above.
Warp
Go to Settings · AI · Manage MCP Servers -> + Add to add an MCP Server. Use the config provided above.
JetBrains AI Assistant
Go to Settings · Tools · AI Assistant · Model Context Protocol (MCP) -> Add. Use the config provided above.
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
Tool
Description
ytdlp_search_videos
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
### 📝 Subtitles & Transcripts
Tool
Description
ytdlp_list_subtitle_languages
List all available subtitle languages for a video
- **Parameters**: `url`
- **Returns**: Available languages, formats, auto-generated status
ytdlp_download_video_subtitles
Download subtitles in VTT format with timestamps
- **Parameters**: `url`, `language` (optional)
- **Returns**: Raw VTT subtitle content
ytdlp_download_transcript
Generate clean plain text transcript
- **Parameters**: `url`, `language` (optional)
- **Returns**: Cleaned text without timestamps or formatting
### 🎥 Video & Audio Downloads
Tool
Description
ytdlp_download_video
Download video to Downloads folder
- **Parameters**: `url`, `resolution`, `startTime`, `endTime`
- **Resolutions**: 480p, 720p, 1080p, best
- **Supports**: Video trimming
ytdlp_download_audio
Extract and download audio only
- **Parameters**: `url`
- **Format**: Best quality M4A/MP3
### 📊 Metadata
Tool
Description
ytdlp_get_video_metadata
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.
ytdlp_get_video_metadata_summary
Get human-readable metadata summary
- **Parameters**: `url`
- **Returns**: Formatted text with key information
### 💬 Comments
Tool
Description
ytdlp_get_video_comments
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
ytdlp_get_video_comments_summary
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
---
## 💡 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 - Detailed tool documentation
- Configuration - Environment variables and settings
- Cookie Configuration - Authentication and private video access
- Error Handling - Common errors and solutions
- Contributing - 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
Allow URLs that resolve to localhost/private/link-local addresses (default: false)
YTDLP_ALLOW_PRIVATE_URLS=false
Only `http`/`https` URLs are accepted, and URLs whose host resolves to a loopback, private, or link-local address (e.g. `localhost`, `192.168.x.x`, `169.254.169.254`) are rejected. Set `YTDLP_ALLOW_PRIVATE_URLS=true` if you need to fetch media from your local network.
> **Limitation:** this check runs once on the URL you pass in, before yt-dlp starts. yt-dlp then makes its own connections, so it does **not** cover HTTP redirects to internal addresses or DNS rebinding. If you run this server where reaching internal services matters (e.g. a shared or cloud-hosted deployment), restrict outbound traffic at the network layer (container network policy, firewall, or blocking `169.254.169.254`).
See the Configuration Guide 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 for detailed setup instructions.
---
## 🏗️ Architecture
### Built With
- **yt-dlp** - Video extraction engine
- **MCP SDK** - Model Context Protocol
- **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):
- 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.
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
📝 License
This project is licensed under the MIT License - see the LICENSE file for details.
🙏 Acknowledgments
- yt-dlp - The amazing video extraction tool
- Anthropic - For the Model Context Protocol
- Dive - MCP-compatible AI platform
📚 Related Projects
- MCP Servers - Official MCP server implementations
- yt-dlp - Command-line video downloader
- Dive Desktop - AI agent platform
⬆ Back to Top
