🎬 yt-dlp-mcp

---

✨ 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 Multi-language support 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

Quick Setup with Dive Desktop

1. Open Dive Desktop
2. Click "+ Add MCP Server"
3. Paste this configuration:

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

1. 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 Parameters: query, maxResults, offset, response_format 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

---

💡 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
• 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

---

🏗️ 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.

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 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

---