# MCP yt-dlp Server

A Model Context Protocol (MCP) server for downloading videos and streams using [yt-dlp](https://github.com/yt-dlp/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](https://github.com/yt-dlp/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](https://github.com/yt-dlp/yt-dlp) or [wiki](https://github.com/yt-dlp/yt-dlp-wiki).

## 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](https://nodejs.org/).

Verify installation:
```bash
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:
```cmd
setup.bat
```

**Linux / macOS:**
```bash
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](https://github.com/yt-dlp/yt-dlp/releases/latest)
2. Place `yt-dlp.exe` in the same directory as the MCP server

**macOS:**
```bash
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:**
```bash
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):**
```bash
pip install yt-dlp
```

For more installation options, see the [yt-dlp installation guide](https://github.com/yt-dlp/yt-dlp/wiki/Installation).

### Step 3: Clone the Repository

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

### Step 4: Install Dependencies

```bash
npm install
```

### Step 5: Configure MCP Client

Add the server to your MCP client configuration:

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

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

```json
{
  "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:
```json
{
  "url": "https://www.youtube.com/watch?v=...",
  "quality": "1080p",
  "subtitles": true
}
```

Download audio only:
```json
{
  "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:**
```json
{
  "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](https://github.com/yt-dlp/yt-dlp/blob/master/supportedsites.md) 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](https://github.com/yt-dlp/yt-dlp) - The powerful video downloader that makes this possible
- [Model Context Protocol](https://modelcontextprotocol.io/) - The protocol enabling AI assistants to use tools