MCP yt-dlp Server

A Model Context Protocol (MCP) server for downloading videos and streams using yt-dlp. This server enables MCP-compatible clients (like Claude Desktop) to download videos from YouTube and 1000+ supported sites, extract audio, download subtitles, and capture live streams.

Credits

This project is built on top of the incredible work by the yt-dlp team. yt-dlp is a feature-rich command-line audio/video downloader that supports thousands of sites. For more information about yt-dlp, visit their GitHub repository or wiki.

Related MCP server: MCP YouTube Downloader

Features

• Video Download: Download videos from YouTube and 1000+ supported sites

• Stream Download: Capture live streams and HLS/m3u8 streams

• Video Info: Get metadata without downloading

• Format Listing: List all available formats for a video

• Search: Search videos directly through yt-dlp extractors

• Audio Extraction: Download audio-only with format conversion (MP3, M4A, WAV, FLAC)

• Subtitles: Download subtitles in multiple languages

• Playlist Support: Download full or partial playlists

Prerequisites

• Node.js 18+

• yt-dlp installed and available in the same directory as the server (or in PATH)

Installation Guide

Step 1: Install Node.js

Download and install Node.js 18+ from nodejs.org.

Verify installation:

node --version
npm --version

Step 2: Download yt-dlp (Easy Method)

We provide setup scripts that automatically download the latest yt-dlp to the correct directory.

Windows: Double-click setup.bat or run in Command Prompt:

setup.bat

Linux / macOS:

chmod +x setup.sh
./setup.sh

The script will:

• Detect your operating system

• Download the latest yt-dlp binary

• Place it in the same directory as the MCP server

• Verify the installation

Step 2 Alternative: Manual Download

If you prefer to install yt-dlp manually:

Windows:

1. Download yt-dlp.exe from the latest releases

2. Place yt-dlp.exe in the same directory as the MCP server

macOS:

curl -L https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp -o /usr/local/bin/yt-dlp
chmod a+rx /usr/local/bin/yt-dlp

Linux:

sudo curl -L https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp -o /usr/local/bin/yt-dlp
sudo chmod a+rx /usr/local/bin/yt-dlp

Python (all platforms):

pip install yt-dlp

For more installation options, see the yt-dlp installation guide.

Step 3: Clone the Repository

git clone https://github.com/timyee22/yt-dlp-MCP.git
cd yt-dlp-MCP

Step 4: Install Dependencies

npm install

Step 5: Configure MCP Client

Add the server to your MCP client configuration:

Claude Desktop (Windows): Edit %APPDATA%\Claude\settings.json:

{
  "mcpServers": {
    "yt-dlp": {
      "command": "node",
      "args": ["C:\\path\\to\\yt-dlp-MCP\\index.js"]
    }
  }
}

Claude Desktop (macOS/Linux): Edit ~/Library/Application Support/Claude/settings.json (macOS) or the appropriate config path:

{
  "mcpServers": {
    "yt-dlp": {
      "command": "node",
      "args": ["/path/to/yt-dlp-MCP/index.js"]
    }
  }
}

Important: Make sure yt-dlp.exe (Windows) or yt-dlp (macOS/Linux) is either:

• In the same directory as index.js

• Or available in your system PATH

Step 6: Restart Claude Desktop

After adding the configuration, restart Claude Desktop to load the new MCP server.

Usage

Once configured, you can ask Claude to:

• "Download this YouTube video: [URL]"

• "Download just the audio from this video as MP3"

• "Get information about this video without downloading it"

• "List all available formats for this video"

• "Search for videos about [topic] on YouTube"

• "Download subtitles for this video in Spanish"

Available Tools

download_video

Download videos from URLs.

Parameters:

• url (required): Video URL

• outputDir: Output directory (default: current directory)

• format: Format selection (default: "best")

• quality: Video quality (e.g., "1080p", "720p")

• audioOnly: Download audio only (default: false)

• audioFormat: Audio format for extraction (default: "mp3")

• subtitles: Download subtitles (default: false)

• subtitleLangs: Subtitle languages (default: "en")

• playlistStart/playlistEnd: Playlist range

• noPlaylist: Download single video only (default: false)

• additionalArgs: Extra yt-dlp arguments

Examples:

Download a YouTube video:

{
  "url": "https://www.youtube.com/watch?v=...",
  "quality": "1080p",
  "subtitles": true
}

Download audio only:

{
  "url": "https://www.youtube.com/watch?v=...",
  "audioOnly": true,
  "audioFormat": "mp3"
}

download_stream

Download live streams or HLS streams.

Parameters:

• url (required): Stream URL

• outputDir: Output directory

• duration: Capture duration in seconds

• format: Format preference (default: "best")

• outputName: Custom output filename

• hlsUseMpegts: Use MPEG-TS for HLS (default: true)

• additionalArgs: Extra arguments

get_video_info

Get video metadata without downloading.

Parameters:

• url (required): Video URL

• flatPlaylist: Faster playlist info (default: false)

list_formats

List all available formats for a URL.

Parameters:

• url (required): Video URL

search_videos

Search for videos using yt-dlp extractors.

Parameters:

• query (required): Search query

• extractor: Search extractor prefix (default: "ytsearch10")

• getInfo: Get detailed info (default: true)

Example:

{
  "query": "programming tutorials",
  "extractor": "ytsearch5"
}

update_yt_dlp

Update yt-dlp to the latest version.

Supported Sites

yt-dlp supports 1000+ sites including:

• YouTube

• Twitch

• Vimeo

• Twitter/X

• Instagram

• TikTok

• Facebook

• SoundCloud

• And many more...

See yt-dlp supported sites for the full list.

Troubleshooting

yt-dlp not found

• Make sure yt-dlp.exe (Windows) or yt-dlp (macOS/Linux) is in the same directory as the server or in your PATH

• On Windows, you may need to add the directory to your PATH environment variable

Node.js errors

• Ensure you have Node.js 18+ installed: node --version

• Make sure dependencies are installed: npm install

Format not available

• Some videos may not have the requested format. Use list_formats to see available options

• YouTube may restrict some formats. Try different quality settings

License

Unlicense

Acknowledgments

• yt-dlp - The powerful video downloader that makes this possible

• Model Context Protocol - The protocol enabling AI assistants to use tools