🎬 yt-dlp-mcp

---

✨ Features

---

🚀 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

📝 Subtitles & Transcripts

🎥 Video & Audio Downloads

📊 Metadata

---

💡 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

---