kevinwatt/yt-dlp-mcp
3.6
If you are the rightful owner of yt-dlp-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
An MCP server implementation that integrates with yt-dlp, providing video and audio content download capabilities for LLMs.
Tools
4
Resources
0
Prompts
0
🎬 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 |
Quick Setup with Dive Desktop
- Open Dive Desktop
- Click "+ Add MCP Server"
- Paste this configuration:
{
"mcpServers": {
"yt-dlp": {
"command": "npx",
"args": ["-y", "@kevinwatt/yt-dlp-mcp"]
}
}
}
- Click "Save" and you're ready! 🎉
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 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
- - Detailed tool documentation
- - Environment variables and settings
- - Common errors and solutions
- - 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
🏗️ 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 .
- 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 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
