🎬 yt-dlp-mcp

<div align="center">

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

</div>

---

✨ Features

<table> <tr> <td width="50%">

🔍 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

</td> <td width="50%">

🎥 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

</td> </tr> </table>

---

🚀 Installation

Prerequisites

Install yt-dlp on your system:

<table> <tr> <th>Platform</th> <th>Command</th> </tr> <tr> <td>🪟 <strong>Windows</strong></td> <td><code>winget install yt-dlp</code></td> </tr> <tr> <td>🍎 <strong>macOS</strong></td> <td><code>brew install yt-dlp</code></td> </tr> <tr> <td>🐧 <strong>Linux</strong></td> <td><code>pip install yt-dlp</code></td> </tr> </table>

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

<details open> <summary><strong>Dive</strong></summary>

1. Open Dive Desktop
2. Click "+ Add MCP Server"
3. Paste the config provided above
4. Click "Save" and you're ready!

</details> <details> <summary><strong>Claude Code</strong></summary>

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

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

</details> <details> <summary><strong>Claude Desktop</strong></summary>

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

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

</details> <details> <summary><strong>Cursor</strong></summary>

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

</details> <details> <summary><strong>VS Code / Copilot</strong></summary>

Install via the VS Code CLI:

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

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

</details> <details> <summary><strong>Windsurf</strong></summary>

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

</details> <details> <summary><strong>Cline</strong></summary>

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

</details> <details> <summary><strong>Warp</strong></summary>

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

</details> <details> <summary><strong>JetBrains AI Assistant</strong></summary>

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

</details>

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

<table> <tr> <th width="30%">Tool</th> <th width="70%">Description</th> </tr> <tr> <td><code>ytdlp_search_videos</code></td> <td>

Search YouTube with pagination and date filtering support

• Parameters: query, maxResults, offset, response_format, uploadDateFilter
• Date Filter: hour, today, week, month, year (optional)
• Returns: Video list with titles, channels, durations, URLs
• Supports: JSON and Markdown formats

</td> </tr> </table>

📝 Subtitles & Transcripts

<table> <tr> <th width="30%">Tool</th> <th width="70%">Description</th> </tr> <tr> <td><code>ytdlp_list_subtitle_languages</code></td> <td>

List all available subtitle languages for a video

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

</td> </tr> <tr> <td><code>ytdlp_download_video_subtitles</code></td> <td>

Download subtitles in VTT format with timestamps

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

</td> </tr> <tr> <td><code>ytdlp_download_transcript</code></td> <td>

Generate clean plain text transcript

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

</td> </tr> </table>

🎥 Video & Audio Downloads

<table> <tr> <th width="30%">Tool</th> <th width="70%">Description</th> </tr> <tr> <td><code>ytdlp_download_video</code></td> <td>

Download video to Downloads folder

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

</td> </tr> <tr> <td><code>ytdlp_download_audio</code></td> <td>

Extract and download audio only

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

</td> </tr> </table>

📊 Metadata

<table> <tr> <th width="30%">Tool</th> <th width="70%">Description</th> </tr> <tr> <td><code>ytdlp_get_video_metadata</code></td> <td>

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.

</td> </tr> <tr> <td><code>ytdlp_get_video_metadata_summary</code></td> <td>

Get human-readable metadata summary

• Parameters: url
• Returns: Formatted text with key information

</td> </tr> </table>

---

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

# Character limit (default: 25000)
YTDLP_CHARACTER_LIMIT=25000

# Max transcript length (default: 50000)
YTDLP_MAX_TRANSCRIPT_LENGTH=50000

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

---