🎬 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>

💬 Comments

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

…