YouTube Downloader MCP server for AI agents

yt-dlp-mcp is a powerful Model Context Protocol (MCP) server that brings video platform capabilities to AI agents. It allows you to search YouTube, download videos, extract metadata, get transcripts, and more through natural language commands, integrating with AI systems like Claude and Dive.

Installation

Prerequisites

You need to install yt-dlp on your system first:

Windows:

winget install yt-dlp

macOS:

brew install yt-dlp

Linux:

pip install yt-dlp

Setup with Dive Desktop

Open Dive Desktop
Click "+ Add MCP Server"
Paste this configuration:

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

Click "Save" to complete setup

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

ytdlp_search_videos: 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

ytdlp_list_subtitle_languages: List all available subtitle languages
- Parameters: url
- Returns: Available languages, formats, auto-generated status
ytdlp_download_video_subtitles: Download subtitles in VTT format
- Parameters: url, language (optional)
- Returns: Raw VTT subtitle content
ytdlp_download_transcript: Generate clean plain text transcript
- Parameters: url, language (optional)
- Returns: Cleaned text without timestamps or formatting

Video & Audio Downloads

ytdlp_download_video: Download video to Downloads folder
- Parameters: url, resolution, startTime, endTime
- Resolutions: 480p, 720p, 1080p, best
- Supports: Video trimming
ytdlp_download_audio: Extract and download audio only
- Parameters: url
- Format: Best quality M4A/MP3

Metadata

ytdlp_get_video_metadata: Extract comprehensive video metadata
- Parameters: url, fields (optional array)
- Returns: Complete metadata or filtered fields
- Includes: Views, likes, upload date, tags, formats, etc.
ytdlp_get_video_metadata_summary: Get human-readable metadata summary
- Parameters: url
- Returns: Formatted text with key information

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"

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

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

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

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

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect