YouTube MCP Server
Connects 'yt-dlp' with LLMs via the Model Context Protocol, allowing users to download YouTube content and integrate it with Dive and other MCP-compatible LLMs.
README Documentation
🎬 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 • Installation • Tools • Usage • Documentation
✨ Features
🔍 Search & Discovery
📊 Metadata Extraction
📝 Transcript & Subtitles
|
🎥 Video Downloads
🎵 Audio Extraction
🛡️ Privacy & 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:
{
"mcpServers": {
"yt-dlp": {
"command": "npx",
"args": ["-y", "@kevinwatt/yt-dlp-mcp@latest"]
}
}
}
MCP Client Configuration
Dive
- Open Dive Desktop
- Click "+ Add MCP Server"
- Paste the config provided above
- Click "Save" and you're ready!
Claude Code
Use the Claude Code CLI to add the yt-dlp MCP server (guide):
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
{
"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:
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
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
|
📝 Subtitles & Transcripts
| Tool | Description |
|---|---|
ytdlp_list_subtitle_languages |
List all available subtitle languages for a video
|
ytdlp_download_video_subtitles |
Download subtitles in VTT format with timestamps
|
ytdlp_download_transcript |
Generate clean plain text transcript
|
🎥 Video & Audio Downloads
| Tool | Description |
|---|---|
ytdlp_download_video |
Download video to Downloads folder
|
ytdlp_download_audio |
Extract and download audio only
|
📊 Metadata
| Tool | Description |
|---|---|
ytdlp_get_video_metadata |
Extract comprehensive video metadata in JSON
|
ytdlp_get_video_metadata_summary |
Get human-readable metadata summary
|
💡 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"
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
# 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
# Character limit (default: 25000)
YTDLP_CHARACTER_LIMIT=25000
# Max transcript length (default: 50000)
YTDLP_MAX_TRANSCRIPT_LENGTH=50000
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/
# 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:
{
"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:
{
"total": 50,
"count": 10,
"offset": 0,
"videos": [...],
"has_more": true,
"next_offset": 10
}
Markdown Format
Human-readable display:
Found 50 videos (showing 10):
1. **Video Title**
📺 Channel: Creator Name
⏱️ Duration: 10:30
🔗 URL: https://...
🔒 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