🎬 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

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

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"]
    }
  }
}

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

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

List all available subtitle languages for a video

• Parameters: url
• Returns: Available languages, formats, auto-generated status

Download subtitles in VTT format with timestamps

• Parameters: url, language (optional)
• Returns: Raw VTT subtitle content

Generate clean plain text transcript

• Parameters: url, language (optional)
• Returns: Cleaned text without timestamps or formatting

🎥 Video & Audio Downloads

Download video to Downloads folder

• Parameters: url, resolution, startTime, endTime
• Resolutions: 480p, 720p, 1080p, best
• Supports: Video trimming

Extract and download audio only

• Parameters: url
• Format: Best quality M4A/MP3

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

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

⬆ Back to Top