# MCP YouTube Downloader

MCP server for downloading videos and audio from YouTube and hundreds of other sites (Vimeo, Twitter, Instagram, etc.) using [yt-dlp](https://github.com/yt-dlp/yt-dlp).

Works with **OpenCode**, **Claude Desktop**, and any MCP-compatible client.

## Features

- Download videos in **mp4**, **webm**, or **mkv** format
- Extract **mp3 audio** from videos
- Select quality: `best`, `2160p`, `1440p`, `1080p`, `720p`, `480p`, `360p`
- Downloads saved to `~/Downloads/yt-downloads/` (cross-platform)
- Supports 1000+ websites (YouTube, Vimeo, Twitter/X, Instagram, TikTok, etc.)

## Prerequisites

- **Python 3.10+**
- **ffmpeg** (required for audio extraction and high-quality video merging)

### Installing ffmpeg

```bash
# Ubuntu/Debian
sudo apt install ffmpeg

# macOS
brew install ffmpeg

# Windows
winget install ffmpeg
```

## Installation

```bash
# Clone the repository
git clone https://github.com/lucassnts963/mcp-youtube-downloader.git
cd mcp-youtube-downloader

# Create virtual environment and install dependencies
python3 -m venv .venv
source .venv/bin/activate  # Linux/macOS
# .venv\Scripts\activate   # Windows

pip install -r requirements.txt
```

## Configuration

### OpenCode

Add to your `opencode.json` (global: `~/.config/opencode/opencode.json` or project-level):

```json
{
  "mcp": {
    "youtube-downloader": {
      "type": "local",
      "command": ["/path/to/mcp-youtube-downloader/.venv/bin/python3", "/path/to/mcp-youtube-downloader/server.py"],
      "enabled": true
    }
  }
}
```

Then restart OpenCode.

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "youtube-downloader": {
      "command": "/path/to/mcp-youtube-downloader/.venv/bin/python3",
      "args": ["/path/to/mcp-youtube-downloader/server.py"]
    }
  }
}
```

Then restart Claude Desktop.

## Usage

Once configured, you can request downloads via chat:

### Examples

```
Download https://www.youtube.com/watch?v=dQw4w9WgXcQ
Baixa esse video como mp3: https://youtu.be/xxxxx
Download this Vimeo video in 1080p: https://vimeo.com/xxxxx
Extrai o audio desse video do twitter: https://x.com/user/status/xxxxx
```

### Parameters

| Parameter | Type | Description | Default |
|-----------|------|-------------|---------|
| `url` | string | Video/audio URL | **required** |
| `format` | enum | `mp4`, `mp3`, `webm`, `mkv` | `mp4` |
| `quality` | enum | `best`, `2160p`, `1440p`, `1080p`, `720p`, `480p`, `360p` | `best` |
| `output_dir` | string | Custom output directory | `~/Downloads/yt-downloads/` |

### Response

```json
{
  "status": "success",
  "title": "Rick Astley - Never Gonna Give You Up",
  "duration": "3m 33s",
  "size_mb": 42.5,
  "format": "mp4",
  "filepath": "/home/user/Downloads/yt-downloads/Rick Astley - Never Gonna Give You Up.mp4"
}
```

## Project Structure

```
mcp-youtube-downloader/
├── server.py          # MCP server implementation
├── requirements.txt   # Python dependencies
├── pyproject.toml     # Project metadata
├── ffmpeg             # Static ffmpeg binary (optional)
├── ffprobe            # Static ffprobe binary (optional)
├── .gitignore
└── README.md
```

## License

MIT