yt-dlp

Download video and audio content from various websites like YouTube, Facebook, and Tiktok using yt-dlp.

GitHub

🎬 yt-dlp-mcp

A powerful MCP server that brings video platform capabilities to your AI agents

npm version License: MIT Node.js Version TypeScript

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

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

🔧 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

⬆ Back to Top

Related Servers