yt-dlp-mcp-server
Allows searching, inspecting metadata, listing formats/subtitles/thumbnails, planning downloads, and downloading videos/audio/subtitles/thumbnails/playlists from YouTube and youtu.be links, as well as post-processing such as remuxing, recoding, audio extraction, embedding assets, splitting/removing chapters, and applying SponsorBlock.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@yt-dlp-mcp-server download the best audio from https://youtu.be/dQw4w9WgXcQ"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
yt-dlp-mcp-server
Deprecated and no longer maintained. This repository is archived and the npm package is deprecated. v0.2.0 is the final release: it gets no bug fixes or security updates, and its dependencies have known vulnerabilities. Don't use it in new projects.
The production-grade MCP server for yt-dlp — inspect, plan, download, postprocess media URLs for AI agents
28 typed tools. YouTube/youtu.be aware. Plan before write. Safe execution. Full yt-dlp option truth.
Quick Start • Tools • Usage Examples • Safety Model • Docker
Why This One
Most yt-dlp MCP servers are thin wrappers around 5–10 commands. This is a control plane for agents:
Other servers | This server | |
Tool count | ~10 | 28 typed tools |
Plan before write | No |
|
Full option truth | Hardcoded flags | 323 options from upstream |
Postprocessing | Basic audio extract | Remux, recode, embed assets, split/remove chapters, SponsorBlock |
Archive management | None | Inspect archive entries, check exact entries, plan archive-safe downloads |
Safe execution | Shell strings | argv arrays, |
Raw escape hatch | Always on | Expert mode, gated behind env flag |
Docker | None | Bundled yt-dlp, ffmpeg, ffprobe, Deno |
Related MCP server: MCP YouTube-DLP
Quick Start
Step 1 — Install media tools
OS | Commands |
Windows |
|
macOS |
|
Ubuntu/Debian | Install Node.js >=22.13 from NodeSource or nodejs.org |
Windows:
yt-dlp.yt-dlpinstalls Deno andyt-dlp.FFmpegas winget dependencies. Restart PowerShell after install so the new command aliases are onPATH.
Step 2 — Add to your MCP client
{
"mcpServers": {
"yt-dlp": {
"command": "npx",
"args": ["-y", "yt-dlp-mcp-server@latest"],
"env": {
"YTDLP_MCP_OUTPUT_ROOT": "/Users/YOUR_USER/Downloads/yt-dlp-mcp"
}
}
}
}Windows: use
"command": "npx.cmd"instead of"npx".
For Codex Desktop on Windows, use the TOML example in Client Setup instead of this JSON shape.
Step 3 — Verify
Ask your AI assistant: "Check the yt-dlp environment" — it will call ytdlp_check_environment and report which tools are found.
Client Setup
Use the config from Step 2 above.
Config file locations:
Claude Desktop macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonClaude Desktop Windows:
%APPDATA%\Claude\claude_desktop_config.jsonCursor:
.cursor/mcp.jsonin a project, or global Cursor MCP settingsWindsurf:
~/.codeium/windsurf/mcp_config.jsonCline: extension MCP settings
claude mcp add-json yt-dlp '{"type":"stdio","command":"npx","args":["-y","yt-dlp-mcp-server@latest"],"env":{"YTDLP_MCP_OUTPUT_ROOT":"~/Downloads/yt-dlp-mcp"}}'VS Code requires a servers root and type field:
{
"servers": {
"yt-dlp": {
"type": "stdio",
"command": "npx",
"args": ["-y", "yt-dlp-mcp-server@latest"],
"env": {
"YTDLP_MCP_OUTPUT_ROOT": "/Users/YOUR_USER/Downloads/yt-dlp-mcp"
}
}
}
}mcp_servers:
yt-dlp:
command: npx
args:
- -y
- yt-dlp-mcp-server@latest
env:
YTDLP_MCP_OUTPUT_ROOT: /Users/YOUR_USER/Downloads/yt-dlp-mcpCodex Desktop usually reads config.toml from:
Windows:
C:\Users\YOUR_USER\.codex\config.tomlmacOS/Linux:
~/.codex/config.toml
[mcp_servers.yt-dlp]
enabled = true
command = "npx"
args = ["-y", "yt-dlp-mcp-server@latest"]
[mcp_servers.yt-dlp.env]
YTDLP_MCP_OUTPUT_ROOT = "/Users/YOUR_USER/Downloads/yt-dlp-mcp"Windows:
[mcp_servers.yt-dlp]
enabled = true
command = "npx.cmd"
args = ["-y", "yt-dlp-mcp-server@latest"]
[mcp_servers.yt-dlp.env]
YTDLP_MCP_OUTPUT_ROOT = 'C:\Users\YOUR_USER\Downloads\yt-dlp-mcp'Docker
Docker bundles everything — yt-dlp, ffmpeg, ffprobe, Deno. No host install required.
docker build -t yt-dlp-mcp-server:local .
mkdir -p "$HOME/Downloads/yt-dlp-mcp"{
"mcpServers": {
"yt-dlp": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-v", "/Users/YOUR_USER/Downloads/yt-dlp-mcp:/downloads",
"-e", "YTDLP_MCP_OUTPUT_ROOT=/downloads",
"yt-dlp-mcp-server:local"
]
}
}
}{
"mcpServers": {
"yt-dlp": {
"command": "docker.exe",
"args": [
"run", "-i", "--rm",
"-v", "C:\\Users\\YOUR_USER\\Downloads\\yt-dlp-mcp:/downloads",
"-e", "YTDLP_MCP_OUTPUT_ROOT=/downloads",
"yt-dlp-mcp-server:local"
]
}
}
}Tools
Environment
Tool | What it does |
| Check host readiness for yt-dlp, ffmpeg, ffprobe, PATH, cookies, plugins, and policy |
| List all supported site extractors from the installed yt-dlp binary |
| List browser impersonation targets for extractor troubleshooting |
Inspect (read-only, no file writes)
Tool | What it does |
| Search YouTube without downloading and return compact video results |
| Inspect title, duration, uploader, formats, subtitles, thumbnails, and selected best format |
| List available quality, codec, resolution, bitrate, and format IDs |
| List manual subtitle and automatic caption languages and formats |
| List thumbnail URLs, resolutions, and poster options |
| Check URL support and identify the yt-dlp extractor without downloading |
Agent routing
When the user asks to download or save a media URL, including youtube.com and youtu.be links, use the download tools rather than trying to download in the model. A request for "best quality" can use the default video format selection, which plans as bestvideo*+bestaudio/best unless the user asks for a different format.
Plan (dry-run, explains before writing)
Tool | What it does |
| Dry-run a download and show output paths, best-quality format, dependencies, risks, and argv |
| Dry-run remux, recode, audio extraction, embedding, chapter, and SponsorBlock workflows |
| Validate typed yt-dlp options and inspect the source-derived option catalog |
Download
Tool | What it does |
| Download a web video URL, including YouTube and youtu.be links, with best-quality/default format support |
| Download or extract audio-only output such as MP3, M4A, Opus, WAV, best audio, or podcast/music extraction |
| Download subtitles or captions, including timestamped transcript files, without downloading the video |
| Download thumbnail, cover image, poster frame, or all thumbnails |
| Download playlist/channel entries with ranges, archive skipping, and max-download controls |
Archive
Tool | What it does |
| List saved entries in a yt-dlp download archive file |
| Check if an exact yt-dlp archive entry is already present |
| Plan archive handling and recommend download-archive usage; does not write the archive |
Download + postprocess
Tool | What it does |
| Download a URL and remux to a different container without re-encoding |
| Download a URL and re-encode video to a target format |
| Download a URL and extract audio as mp3, m4a, opus, etc. |
| Download a URL and embed subtitles, thumbnails, metadata, or chapters |
| Download a URL and split media into one file per chapter |
| Download a URL and remove chapters matching regex filters |
| Download a URL and remove or mark SponsorBlock segments |
Expert
Tool | What it does |
| Last-resort raw yt-dlp argv escape hatch; requires |
Usage Examples
Search and discover
"Search for Python tutorials on YouTube"
"Find the top 10 machine learning videos from this week"
"What formats are available for this video?"
"List all subtitle languages for https://youtube.com/watch?v=..."Inspect before committing
"What metadata does this video have?"
"Check if this URL is supported"
"List all available formats with their codecs and bitrates"
"Plan a 720p download of this video — what will it create?"Download
"Download this video in 720p: https://youtube.com/watch?v=..."
"Download just the audio as MP3"
"Download English auto-generated subtitles"
"Download this video from 1:30 to 3:00 only"
"Download playlist items 1–10 and skip ones I've already downloaded"Postprocess
"Extract MP3 audio from this URL"
"Download this URL and remux it to MP4 without re-encoding"
"Download this URL and embed subtitles and thumbnail"
"Download this URL and split it into chapters"
"Download this URL and remove sponsor segments using SponsorBlock"Archive management
"Check if this exact archive entry is already in my archive"
"Show me everything in my download archive"
"Plan how to archive-protect this playlist download"Safety Model
Policy | Behavior |
Process execution |
|
Planning | Download and postprocess tools call the planner before writing any file |
Output roots | All output paths constrained under managed roots by default |
Archives | Archive paths resolve under output root unless arbitrary paths are enabled |
Config files | Cookie/browser/netrc sources require |
Raw args | Normal tools take typed inputs only; expert mode is gated |
Redaction | Cookies, PO tokens, auth headers, signed URL params redacted in previews and errors |
Environment Variables
Variable | Default | Purpose |
|
| Managed output directory |
| OS temp + | Managed temp directory |
| auto-detected | Override yt-dlp binary path |
| auto-detected | Override ffmpeg binary path |
| auto-detected | Override ffprobe binary path |
|
| Enable |
|
| Allow paths outside managed roots |
|
| Allow cookie/netrc/config file inputs |
| — | Server-approved cookies file |
| — | Server-approved browser cookie source |
|
| Per-command timeout |
|
| Max retained stdout/stderr |
If doctor reports missing binaries that work in your terminal, set explicit paths:
{
"YTDLP_MCP_YTDLP_PATH": "/opt/homebrew/bin/yt-dlp",
"YTDLP_MCP_FFMPEG_PATH": "/opt/homebrew/bin/ffmpeg",
"YTDLP_MCP_FFPROBE_PATH": "/opt/homebrew/bin/ffprobe"
}Use /usr/local/bin/... for Intel Homebrew on macOS. Use absolute .exe paths on Windows.
CLI
The yt-dlp-mcp-server binary is useful for humans and quiet when launched by an MCP client.
yt-dlp-mcp-server doctor # check environment
yt-dlp-mcp-server doctor --json # machine-readable
yt-dlp-mcp-server print-config --client claude --mode npx
yt-dlp-mcp-server print-config --client codex --mode npx --os windows
yt-dlp-mcp-server print-config --client all --mode docker
yt-dlp-mcp-server print-deps --os macos
yt-dlp-mcp-server print-deps --os windows --manager winget
yt-dlp-mcp-server print-deps --os linux --manager apt
yt-dlp-mcp-server stdio # start MCP server explicitlySupported --client values: claude, cursor, windsurf, cline, vscode, warp, codex, all.
Resources and Prompts
The server exposes MCP resources and prompt templates:
Type | Name | Purpose |
Resource |
| Tool inventory and capability summary |
Resource |
| Full 323-option catalog by group |
Resource |
| Current safety policy settings |
Resource |
| Common errors and fixes |
Resource |
| Live environment check snapshot |
Prompt |
| Guided workflow for archive-protected playlist downloads |
Prompt |
| Guided format selection for minimal file size |
Development
pnpm install
pnpm run validate:ci # typecheck + tests + build + MCP contract + output audit
pnpm run validate:local # above + live smoke tests (requires host media tools)
pnpm run validate:release # above + Docker smoke testsMCP Inspector for manual UX check:
npx -y @modelcontextprotocol/inspector node dist/index.jsLicense
MIT — see LICENSE.
Available Tools
28 toolsytdlp_apply_sponsorblockYtdlp Apply SponsorblockA
Download a media URL and apply SponsorBlock mark or remove options. Use when the user asks to mark, remove, or chapter SponsorBlock categories during download.
Inputs: url (required), auth, dryRun, format, +9 more. Returns: ok, data, error
ytdlp_check_archiveYtdlp Check ArchiveARead-onlyIdempotent
Check whether an exact yt-dlp archive entry string exists in an archive file under the configured filesystem policy. This does not resolve a video URL into its archive ID.
Inputs: archivePath (required), entry. Returns: ok, data, error
ytdlp_check_environmentYtdlp Check EnvironmentARead-onlyIdempotent
Check whether this MCP server can run yt-dlp workflows on the host. Use before the first download or when PATH, ffmpeg, ffprobe, cookies, plugins, or policy settings may be misconfigured.
Inputs: no named parameters. Returns: ok, data, error
ytdlp_download_audioYtdlp Download AudioA
Download or extract audio from a web media URL to the managed output root.
Use when: The user asks for audio-only output, MP3, M4A, Opus, WAV, best audio, podcast/music extraction, or keeping audio without video. Don't use when: The user needs a video file with visuals, subtitles only, thumbnails only, metadata, or a dry-run plan.
Note: This creates local audio files under the configured output root.
Inputs: url (required), auth, kind, dryRun, +10 more. Returns: ok, data, error
ytdlp_download_playlistYtdlp Download PlaylistA
Download playlist, channel, or multi-video URL entries to the managed output root. Use when the user asks to download a playlist/channel, select playlist ranges, skip existing archive entries, cap max downloads, randomize order, or stop on existing files.
Inputs: url (required), auth, kind, dryRun, +10 more. Returns: ok, data, error
ytdlp_download_subtitlesYtdlp Download SubtitlesA
Download subtitles or captions for a media URL without downloading the video. Use when the user asks for subtitle languages, auto captions, subtitle formats, subtitle files, transcripts with timestamps, or subtitle conversion.
Inputs: url (required), auth, kind, dryRun, +10 more. Returns: ok, data, error
ytdlp_download_thumbnailYtdlp Download ThumbnailB
Download thumbnail image files for a media URL without downloading the video. Use when the user asks for a cover image, thumbnail, poster frame, or all thumbnails.
Inputs: url (required), auth, kind, dryRun, +10 more. Returns: ok, data, error
ytdlp_download_videoYtdlp Download VideoA
Download a web video URL to the managed output root, including YouTube and youtu.be links.
Use when: The user asks to download, save, fetch, or get a local video file from a media URL; asks for best quality/highest quality; asks for a specific format/resolution; asks to trim sections; or asks for overwrite behavior. Don't use when: The user only wants audio, subtitles, thumbnails, metadata, or a dry-run plan.
Note: This is the intended MCP path for permitted user-provided media download requests such as "download in best quality". Default video format selection plans as bestvideo*+bestaudio/best unless the user asks otherwise. This creates local files under the configured output root.
Inputs: url (required), auth, kind, dryRun, +10 more. Returns: ok, data, error
ytdlp_embed_assetsYtdlp Embed AssetsA
Download a media URL and embed subtitles, thumbnail, metadata, chapters, or infojson into the output file. Use when the user asks for a self-contained media file with embedded assets.
Inputs: url (required), auth, dryRun, format, +9 more. Returns: ok, data, error
ytdlp_execute_expertYtdlp Execute ExpertADestructive
Execute reviewed raw yt-dlp argv only when typed tools cannot express the request. Disabled unless YTDLP_MCP_ENABLE_EXPERT=true; dry-run is default and unsafe/path-gated flags are blocked by policy.
Inputs: url, args, dryRun, output. Returns: ok, data, error
ytdlp_extract_audioYtdlp Extract AudioB
Download a media URL and extract an audio file with ffmpeg/ffprobe. Use when the user asks for MP3, M4A, Opus, WAV, best audio, or audio-only output.
Inputs: url (required), auth, dryRun, format, +9 more. Returns: ok, data, error
ytdlp_get_metadataYtdlp Get MetadataBRead-onlyIdempotent
Extract structured metadata for a media URL without downloading files using yt-dlp --dump-json. Use to inspect title, duration, uploader, formats, subtitles, thumbnails, and selected best format.
Inputs: url (required), auth, limit, offset, +3 more. Returns: ok, data, error
ytdlp_inspect_archiveYtdlp Inspect ArchiveBRead-onlyIdempotent
Read a yt-dlp download archive file under the configured filesystem policy and return its saved archive entries. Use when the user asks what is already in an archive.
Inputs: archivePath (required), entry. Returns: ok, data, error
ytdlp_list_extractorsYtdlp List ExtractorsARead-onlyIdempotent
List all site extractors supported by the installed yt-dlp binary. Use when the user asks whether a website or URL family is supported.
Inputs: no named parameters. Returns: ok, data, error
ytdlp_list_formatsYtdlp List FormatsARead-onlyIdempotent
List available audio/video formats for a media URL without downloading files. Use when the user asks what quality, codec, resolution, bitrate, or format IDs are available.
Inputs: url (required), auth, limit, offset, +3 more. Returns: ok, data, error
ytdlp_list_impersonation_targetsYtdlp List Impersonation TargetsARead-onlyIdempotent
List browser impersonation targets supported by the installed yt-dlp binary. Use when a download needs browser-like request headers or extractor troubleshooting.
Inputs: no named parameters. Returns: ok, data, error
ytdlp_list_subtitlesYtdlp List SubtitlesARead-onlyIdempotent
List available manual subtitles and automatic captions for a media URL without downloading files. Use when the user asks which subtitle languages or formats exist.
Inputs: url (required), auth, limit, offset, +3 more. Returns: ok, data, error
ytdlp_list_thumbnailsYtdlp List ThumbnailsBRead-onlyIdempotent
List available thumbnails for a media URL without downloading files. Use when the user asks for cover images, thumbnail URLs, resolutions, or poster options.
Inputs: url (required), auth, limit, offset, +3 more. Returns: ok, data, error
ytdlp_plan_downloadYtdlp Plan DownloadARead-onlyIdempotent
Dry-run a video, audio, subtitle, thumbnail, or playlist download without writing files. Use to answer what would happen, which format best quality resolves to, required dependencies, output paths, risks, and exact yt-dlp argv.
Inputs: url (required), auth, kind, format, +9 more. Returns: ok, data, error
ytdlp_plan_postprocessYtdlp Plan PostprocessARead-onlyIdempotent
Dry-run post-processing without writing files. Use to explain ffmpeg requirements, output policy, risks, and side effects for remux, recode, audio extraction, embedded assets, chapters, or SponsorBlock.
Inputs: url, auth, format, output, +4 more. Returns: ok, data, error
ytdlp_probe_urlYtdlp Probe UrlARead-onlyIdempotent
Probe whether yt-dlp supports a media URL and identify the extractor without downloading files. Use for quick support checks before planning or downloading.
Inputs: url (required), auth, limit, offset, +3 more. Returns: ok, data, error
ytdlp_recodeYtdlp RecodeA
Download a media URL and re-encode the resulting video with ffmpeg, defaulting to MP4. Use when the user asks for a target video format and accepts re-encoding.
Inputs: url (required), auth, dryRun, format, +9 more. Returns: ok, data, error
ytdlp_remove_chaptersYtdlp Remove ChaptersA
Download a media URL and remove chapters matching configured regex filters, defaulting to sponsor-like chapters. Use for chapter removal workflows that need ffmpeg cuts.
Inputs: url (required), auth, dryRun, format, +9 more. Returns: ok, data, error
ytdlp_remuxYtdlp RemuxA
Download a media URL and remux the resulting video container with ffmpeg, defaulting to MP4 without re-encoding. Use when the user asks to convert containers such as MKV/WebM to MP4.
Inputs: url (required), auth, dryRun, format, +9 more. Returns: ok, data, error
ytdlp_search_videosYtdlp Search VideosARead-onlyIdempotent
Search YouTube through yt-dlp without downloading media and return compact video results. Use when the user asks to find videos before choosing one to inspect or download.
Inputs: query (required), auth, limit, offset, +2 more. Returns: ok, data, error
ytdlp_split_chaptersYtdlp Split ChaptersA
Download a media URL and split the result into one file per chapter. Use when the user asks to create separate chapter files or segment a chaptered video.
Inputs: url (required), auth, dryRun, format, +9 more. Returns: ok, data, error
ytdlp_update_archiveYtdlp Update ArchiveARead-onlyIdempotent
Return a safe archive-update plan and recommendation without writing the archive. Prefer using downloadArchive on download tools so yt-dlp writes canonical extractor IDs.
Inputs: archivePath (required), entry. Returns: ok, data, error
ytdlp_validate_optionsYtdlp Validate OptionsARead-onlyIdempotent
Validate typed yt-dlp option input and expose the source-derived option catalog. Use to answer whether a flag or option is supported without executing yt-dlp.
Inputs: url, auth, kind, format, +9 more. Returns: ok, data, error
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 28 tools
Each tool targets a distinct operation: environment checks, extractor listing, searching, metadata, format/subtitle/thumbnail listing, planning, downloading different media types, and various post-processing steps. Descriptions are detailed and clearly differentiate overlapping actions like extract_audio vs download_audio.
All tools follow a consistent 'ytdlp_' prefix with verb_noun pattern (e.g., list_extractors, download_video, plan_download). No mixing of conventions; every name clearly indicates the action and target.
With 28 tools, the count is on the high side but justified by yt-dlp's extensive capabilities. Each tool fills a specific niche; however, some tools like the multiple post-processing variants could potentially be simplified. Still, the set is well-scoped for comprehensive media management.
The surface covers virtually all typical yt-dlp workflows: environment checks, extractor listing, search, metadata, format/subtitle/thumbnail handling, various download types (video, audio, subtitles, thumbnails, playlists), post-processing (remux, recode, embed, chapters, SponsorBlock), archive management, and an expert fallback. No obvious gaps for a media download tool.
Maintenance
Related MCP Connectors
Turn any video or audio link into files, transcripts and metadata, right from your AI agent.
YouTube for AI agents: transcripts, comments, video stats, channel monitor, Shorts captions.
YouTube transcripts, search, channels, playlists and bulk transcript jobs for AI agents. 14 tools.
YouTube transcripts, search, channel/playlist listings and upload tracking for AI agents.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables searching, retrieving metadata, and downloading YouTube videos or audio without requiring an API key. It utilizes yt-dlp to support media retrieval and playlist management within MCP-compliant clients like Claude and Cursor.813 PyPI1MIT
- FlicenseNot gradedqualityDmaintenanceProvides tools for downloading YouTube videos and audio using yt-dlp, enabling integration with AI assistants via MCP.5-
- AlicenseAqualityCmaintenanceEnables AI agents to download, transcribe, and read metadata for any video or audio URL - YouTube, TikTok, X, podcasts and 1000+ sites - working from agent sandboxes and servers where direct downloads usually get blocked. $3 free credit, no card.928 npmMIT
- FlicenseNot gradedqualityBmaintenanceEnables downloading videos and audio from various platforms via yt-dlp, with configurable quality, batch downloads, progress tracking, cancellation, and retry mechanisms.-