🎬 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

Related MCP server: YouTube MCP Integration

🚀 Installation

Prerequisites

Install yt-dlp on your system:

Getting Started

Add the following config to your MCP client:

MCP Client Configuration

1. Open Dive Desktop

2. Click "+ Add MCP Server"

3. Paste the config provided above

4. Click "Save" and you're ready!

Use the Claude Code CLI to add the yt-dlp MCP server (guide):

Add to your claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

Go to Cursor Settings -> MCP -> New MCP Server. Use the config provided above.

Install via the VS Code CLI:

Or follow the MCP install guide with the standard config from above.

Follow the configure MCP guide using the standard config from above.

Follow Cline MCP configuration guide and use the config provided above.

Go to Settings | AI | Manage MCP Servers -> + Add to add an MCP Server. Use the config provided above.

Go to Settings | Tools | AI Assistant | Model Context Protocol (MCP) -> Add. Use the config provided above.

Manual Installation

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

Get Metadata

Download Subtitles & Transcripts

Download Content

📖 Documentation

• API Reference - Detailed tool documentation

• Configuration - Environment variables and settings

• Cookie Configuration - Authentication and private video access

• Error Handling - Common errors and solutions

• Contributing - How to contribute

🔧 Configuration

Environment Variables

Cookie Configuration

To access private videos, age-restricted content, or avoid rate limits, configure cookies:

MCP Configuration with cookies:

Supported browsers: brave, chrome, chromium, edge, firefox, opera, safari, vivaldi, whale

See Cookie Configuration Guide for detailed setup instructions.

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

Markdown Format

Human-readable display:

🔒 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