ytdl-mcp

ytdl-mcp

A cross-platform, single-binary MCP server that downloads media from any yt-dlp-supported site (YouTube, Vimeo, …), embeds metadata and cover art, organizes files by artist, and transfers the result to a directory on an SSH remote — over rsync (with an scp fallback for hosts that lack it, e.g. Windows).

Written in Rust on the rmcp crate. yt-dlp and ffmpeg are auto-downloaded into a per-user cache on first run, so the host needs neither pre-installed — the one binary is the whole install.

---

Features

• Audio, video, or both — audio-first by default, with separate remote destinations for audio and video.
• Proper tagging — embeds title / artist / album / date and cover art, and organizes output as Artist/Title [id].ext so media servers (Plex, etc.) index it cleanly. A non-greedy Artist - Title parse recovers the artist from free-form video titles. Source .info.json, thumbnail, and description sidecars are preserved next to the media for future retagging/indexing. Common YouTube title noise like (Official Video), [Official Audio], and trailing channel handles is stripped from embedded title metadata by default.
• Self-contained paths — the binary downloads/caches yt-dlp + ffmpeg when run directly; the container image bakes in ffmpeg, fpcalc, SSH, and rsync for media-host batch jobs.
• Self-installing — ytdl-mcp setup registers the server into Claude Code, Codex, and/or Gemini CLI via each tool's own mcp add.
• Robust transfers — rsync --protect-args when present, scp otherwise; non-interactive SSH (BatchMode=yes, StrictHostKeyChecking=accept-new) so a TTY-less server never hangs on a prompt. On transfer failure the local staging copy is kept for retry.
• Repeat-safe — use_archive records downloaded IDs (per mode) and skips them on later runs; YouTube mix/radio URLs are auto-cleaned to the seed video.
• Stats-ready ledger — every completed download call appends a JSONL entry with timestamp, destinations, files, bytes, uploader, and transfer status.
• Plex playlist sync — when Plex credentials are configured, downloaded audio is added to yt-dlp Downloads by default.

Tools

Tool	Purpose
youtube_search	Search YouTube with yt-dlp and return result URLs without downloading.
youtube_search_ui	Open an interactive YouTube search UI in MCP App-capable hosts.
youtube_download	Download one or more URLs (audio/video/both) and rsync/scp them to a remote dir.
youtube_probe	Read-only: resolve title/duration/uploader/format counts without downloading.
youtube_identify	Fingerprint local audio with fpcalc, return AcoustID/MusicBrainz candidates, preview canonical tags, and optionally write high-confidence tags.
youtube_stats	Summarize the download ledger: totals, file kinds, uploaders, and recent entries.

youtube_download parameters

Param	Default	Meaning
urls	— (required)	One URL string or an array of URLs.
mode	audio	audio, video, or both.
audio_format	env YTDLP_AUDIO_FORMAT → mp3	mp3/m4a/opus/flac/wav/best.
audio_quality	0	yt-dlp quality for lossy codecs: 0–9 or a bitrate like 192K.
max_height	best	Cap video resolution (e.g. 1080).
container	mp4	mp4 or mkv for video.
remote	env YTDLP_REMOTE	SSH alias or user@host.
dest_path	env YTDLP_REMOTE_PATH	Absolute remote dir for audio.
video_dest_path	env YTDLP_VIDEO_REMOTE_PATH → dest_path	Absolute remote dir for video.
keep_local	false	Keep the local staging copy after transfer.
use_archive	false	Record + skip already-downloaded IDs (per mode).
plex_playlist	env YTDLP_PLEX_PLAYLIST → yt-dlp Downloads when Plex is configured	Plex playlist title or ID to add downloaded audio tracks to. Requires YTDLP_PLEX_URL and YTDLP_PLEX_TOKEN.
response_format	markdown	markdown or json.

When Plex credentials are configured, successful downloads that produced audio files search Plex for each downloaded track, create the target playlist if needed, and add missing tracks while skipping entries already present. The default playlist is yt-dlp Downloads; set YTDLP_PLEX_PLAYLIST or pass plex_playlist to override it. Plex errors are reported as plex_playlist_error and do not make the completed download fail. JSON responses include a plex_playlist summary with matched, added, already_present, and missing counts.