youtube-mcp-download

YouTube Video Downloader

A comprehensive collection of Python tools for downloading YouTube content using yt-dlp, including both simple scripts and an advanced MCP server.

Tools

1. Simple Scripts

Single Video Downloader (youtube_downloader.py)

Downloads individual YouTube videos with progress tracking.

Playlist Downloader (playlist_downloader.py)

Downloads entire YouTube playlists with organization.

2. MCP Server (youtube_mcp_server_fastmcp.py)

An advanced MCP (Model Context Protocol) server using FastMCP that provides:

• Asynchronous video and playlist downloads
• Job tracking and status monitoring
• SQLite database for metadata storage
• Comprehensive library management
• Claude Desktop integration

Features

Simple Scripts

Single Video Downloader

• ✅ Prompts user for YouTube URL
• ✅ Downloads the best quality video available
• ✅ Creates a downloads folder for saved videos
• ✅ Shows download progress
• ✅ Handles errors gracefully
• ✅ Auto-installs yt-dlp if not present
• ✅ No pytube dependency (as requested)

Playlist Downloader

• ✅ Prompts user for YouTube playlist URL
• ✅ Downloads entire playlists (up to 50 videos by default)
• ✅ Creates organized folders for each playlist
• ✅ Shows playlist information before downloading
• ✅ Downloads videos with playlist index numbers
• ✅ Auto-installs yt-dlp if not present
• ✅ Confirmation prompt before downloading large playlists

MCP Server Features

• ✅ Asynchronous Downloads: Start downloads and get job IDs for tracking
• ✅ Job Status Monitoring: Check download progress and status
• ✅ Metadata Database: SQLite database with video/playlists info
• ✅ Library Management: Browse all downloaded content
• ✅ Error Handling: Comprehensive error tracking and reporting
• ✅ Concurrent Downloads: Multiple downloads can run simultaneously
• ✅ Rich Metadata: Stores titles, descriptions, duration, file paths, etc.

Requirements

• Python 3.11+
• yt-dlp (automatically installed if missing)
• MCP SDK (automatically installed if missing)

Usage

Single Video Download

1. Run the single video downloader:

   python3 youtube_downloader.py

1. Enter a YouTube URL when prompted

1. The video will be downloaded to the downloads folder

Playlist Download

1. Run the playlist downloader:

   python3 playlist_downloader.py

1. Enter a YouTube playlist URL when prompted

1. Review playlist information and confirm download

1. All videos will be downloaded to a playlist-specific folder

MCP Server Usage

The MCP server provides four main tools for asynchronous downloading and library management.

Using with uv (Recommended)

1. Install dependencies and run:

   cd /Users/granludo/code/testing/youtube_download
   uv sync
   uv run python start_server.py

Direct Python Usage

python3 youtube_mcp_server_fastmcp.py

Available MCP Tools

1. download_video - Start async video download
2. download_playlist - Start async playlist download
3. get_download_status - Monitor download progress
4. cancel_download - Cancel running downloads
5. list_downloads - Browse all download jobs
6. get_video_metadata - Get video info without downloading

Examples

Single Video Example

$ python3 youtube_downloader.py

==================================================
YouTube Video Downloader
==================================================
Enter YouTube URL: https://www.youtube.com/watch?v=dQw4w9WgXcQ
📥 Downloading video from: https://www.youtube.com/watch?v=dQw4w9WgXcQ
✓ Download completed!
📁 Files saved to: /path/to/downloads

Playlist Example

$ python3 playlist_downloader.py

==================================================
YouTube Playlist Downloader
==================================================
Enter YouTube Playlist URL: https://www.youtube.com/playlist?list=PLrAXtmRdnEQy5rhxJj7aKre_2qO5yQ5nI
📊 Analyzing playlist...
📋 Playlist name: My Music Playlist
🎥 Number of videos: 25

🔄 Download 25 videos? (y/N): y
📥 Downloading playlist: My Music Playlist
✓ Playlist download completed!
📁 All videos saved to: /path/to/playlists/My Music Playlist

MCP Server Examples

Using with uv

1. Install and run the server:

   cd /Users/granludo/code/testing/youtube_download
   uv sync                    # Install dependencies
   uv run python start_server.py  # Start server

1. The server will start silently (no stdout output, as required by MCP protocol)

MCP Tool Examples

Tool 1: Download Single Video ``json { "name": "download_video", "arguments": { "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "output_dir": "downloads" } } ` Response: "Download started successfully. Job ID: abc123-def456-ghi789"`

Tool 2: Download Playlist ``json { "name": "download_playlist", "arguments": { "url": "https://www.youtube.com/playlist?list=PLrAXtmRdnEQy5rhxJj7aKre_2qO5yQ5nI", "output_dir": "playlists" } } ` Response: "Playlist download started successfully. Job ID: def456-ghi789-jkl012"`

Tool 3: Check Download Status ``json { "name": "get_download_status", "arguments": { "job_id": "abc123-def456-ghi789" } } `` Response: JSON object with job status, progress, and metadata

Tool 4: List Downloads ``json { "name": "list_downloads", "arguments": {} } ` Response: `` 📹 VIDEOS:

• Never Gonna Give You Up (ID: video-uuid-123)

Path: /downloads/Never Gonna Give You Up.mp4 Duration: 213s

📁 PLAYLISTS:

• Music Collection (ID: playlist-uuid-456)

Videos: 25 Path: /playlists/Music Collection ```

Complete Workflow Example

1. Configure Claude Desktop - Add the MCP server to your claude_desktop_config.json:

   {
     "mcpServers": {
       "youtube-mcp-tools": {
         "command": "/opt/homebrew/bin/uv",
         "args": [
           "--directory",
           "/Users/granludo/code/testing/youtube_download",
           "run",
           "start_server.py"
         ]
       }
     }
   }

1. Download a video in Claude:

   "Download this YouTube video: https://www.youtube.com/watch?v=jNQXAC9IVRw"

The server will start the download and return a job ID immediately.

1. Check download status:

   "What's the status of that download?"

1. List all downloads:

   "Show me all my download jobs"

Notes

Simple Scripts

• Both scripts will automatically install yt-dlp if it's not found
• Videos are saved with their original titles
• Playlist videos are numbered by their position in the playlist
• The playlist downloader limits downloads to 50 videos by default (adjustable)
• Both scripts handle keyboard interrupts gracefully
• Downloads are organized in separate folders for videos vs playlists

MCP Server

• Uses FastMCP for simplified MCP server implementation
• Creates youtube_library.db SQLite database for metadata
• Supports up to 3 concurrent downloads
• Job tracking with unique UUIDs for each download
• Rich metadata storage including titles, descriptions, duration, file paths
• Asynchronous downloads that return immediately with job IDs
• Comprehensive error handling and logging
• Compatible with Claude Desktop and other MCP clients