yt-dlp-mcp

🎬 yt-dlp-mcp

✨ Features

🚀 Installation

Prerequisites

Install yt-dlp on your system:

Getting Started

Add the following config to your MCP client:

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

MCP Client Configuration

claude mcp add yt-dlp npx @kevinwatt/yt-dlp-mcp@latest

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

code --add-mcp '{"name":"yt-dlp","command":"npx","args":["-y","@kevinwatt/yt-dlp-mcp@latest"]}'

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

💬 Comments

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

Get Comments

"Get the top 20 comments for https://youtube.com/watch?v=..."
"Get comments as threaded JSON for this video"
"Extract comments as markdown_tree so the reply branches stay intact"
"Get newest comments with maxDepth 1 and maxRepliesPerThread 0"
"Summarize comments in threaded view"

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
• Cookie Configuration - Authentication and private video access
• 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

See the Configuration Guide for the full list.

Proxy and yt-dlp Config File

All tools read your yt-dlp config file (~/.config/yt-dlp/config), so any --proxy, --cookies or other options set there apply automatically. This is the only channel available to MCP clients that cannot pass environment variables to the server process.

These are alternatives — set only the one you need:

Supported proxy schemes: http, https, socks4, socks5, socks5h.

YTDLP_IGNORE_CONFIG=1 is not a straight revert to 0.9.x. The search, metadata and comments tools always read the config file, so this setting stops them from doing so as well.

MCP Configuration with a proxy:

{
  "mcpServers": {
    "yt-dlp": {
      "command": "npx",
      "args": ["-y", "@kevinwatt/yt-dlp-mcp@latest"],
      "env": {
        "YTDLP_PROXY": "socks5://127.0.0.1:1080"
      }
    }
  }
}

If your MCP client cannot pass environment variables to the server, put the options in ~/.config/yt-dlp/config instead — every tool reads that file:

--proxy socks5://127.0.0.1:1080
--cookies /path/to/cookies.txt

Note: Your config file applies to downloads as well. Options that change the output format (-x, --remux-video, --recode-video) change what the download tools produce; the tools report the file yt-dlp actually wrote, so the reported name stays correct. Output-location options (-o, -P) have no effect, because the tools always pass an absolute --output on the command line, which takes precedence.

Note: yt-dlp config files can contain options that execute commands (--exec, --postprocessor-args, --ffmpeg-location). These now run on tool invocations too, including ones triggered by an AI assistant. Set YTDLP_IGNORE_CONFIG=1 if you would rather the server ignore your config file entirely.

Cookie Configuration

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

⚠️ Important: Cookie authentication requires a JavaScript runtime (deno) to be installed. When using cookies, YouTube uses authenticated API endpoints that require JavaScript challenge solving. Without deno, downloads will fail with "n challenge solving failed" error.

Install deno: https://docs.deno.com/runtime/getting_started/installation/

# Extract cookies from browser (recommended)
YTDLP_COOKIES_FROM_BROWSER=chrome

# Or use a cookie file
YTDLP_COOKIES_FILE=/path/to/cookies.txt

MCP Configuration with cookies:

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

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:

{
  "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://...

Comment Markdown Tree

Useful for LLM analysis when reply context matters:

# AI-Ready Comment Threads

source_title: "Sample Video"
comments_detected: 20
root_threads: 6
reply_comments: 14

## Threads

### Thread 1

- comment_id: "abc123"
  parent_id: "root"
  depth: 0
  reply_count: 2
  text:
    | Root comment text
  - comment_id: "reply456"
    parent_id: "abc123"
    depth: 1
    reply_count: 0
    text:
      | Reply text

Comment Limits

YouTube comment extraction supports the full extractor tuple:

youtube:comment_sort=<sort>;max_comments=<total>,<parents>,<replies>,<repliesPerThread>,<depth>

Examples:

• Default behavior: maxComments=20 yields max_comments=20,20,20,20,2
• Root-only comments: maxDepth=1, maxRepliesPerThread=0
• Limited branching: maxReplies=40, maxRepliesPerThread=5, maxDepth=2

🔒 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