MCP YouTube Downloader

MCP server for downloading videos and audio from YouTube and hundreds of other sites (Vimeo, Twitter, Instagram, etc.) using 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

# Ubuntu/Debian
sudo apt install ffmpeg

# macOS
brew install ffmpeg

# Windows
winget install ffmpeg

Installation

# 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):

{
  "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:

{
  "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

{
  "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