Skip to main content
Glama

yt-dlp-mcp-server

WARNING

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

npm version License: MIT Node.js Version TypeScript

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

ytdlp_plan_download explains paths, deps, risks

Full option truth

Hardcoded flags

323 options from upstream yt_dlp.options.create_parser()

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, shell: false, managed output roots, redaction

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

winget install -e --id OpenJS.NodeJS.LTSwinget install -e --id yt-dlp.yt-dlp

macOS

brew install node yt-dlp ffmpeg

Ubuntu/Debian

Install Node.js >=22.13 from NodeSource or nodejs.orgsudo apt install -y ffmpeg pipx && pipx install yt-dlp

Windows: yt-dlp.yt-dlp installs Deno and yt-dlp.FFmpeg as winget dependencies. Restart PowerShell after install so the new command aliases are on PATH.

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.json

  • Claude Desktop Windows: %APPDATA%\Claude\claude_desktop_config.json

  • Cursor: .cursor/mcp.json in a project, or global Cursor MCP settings

  • Windsurf: ~/.codeium/windsurf/mcp_config.json

  • Cline: 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-mcp

Codex Desktop usually reads config.toml from:

  • Windows: C:\Users\YOUR_USER\.codex\config.toml

  • macOS/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

ytdlp_check_environment

Check host readiness for yt-dlp, ffmpeg, ffprobe, PATH, cookies, plugins, and policy

ytdlp_list_extractors

List all supported site extractors from the installed yt-dlp binary

ytdlp_list_impersonation_targets

List browser impersonation targets for extractor troubleshooting

Inspect (read-only, no file writes)

Tool

What it does

ytdlp_search_videos

Search YouTube without downloading and return compact video results

ytdlp_get_metadata

Inspect title, duration, uploader, formats, subtitles, thumbnails, and selected best format

ytdlp_list_formats

List available quality, codec, resolution, bitrate, and format IDs

ytdlp_list_subtitles

List manual subtitle and automatic caption languages and formats

ytdlp_list_thumbnails

List thumbnail URLs, resolutions, and poster options

ytdlp_probe_url

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

ytdlp_plan_download

Dry-run a download and show output paths, best-quality format, dependencies, risks, and argv

ytdlp_plan_postprocess

Dry-run remux, recode, audio extraction, embedding, chapter, and SponsorBlock workflows

ytdlp_validate_options

Validate typed yt-dlp options and inspect the source-derived option catalog

Download

Tool

What it does

ytdlp_download_video

Download a web video URL, including YouTube and youtu.be links, with best-quality/default format support

ytdlp_download_audio

Download or extract audio-only output such as MP3, M4A, Opus, WAV, best audio, or podcast/music extraction

ytdlp_download_subtitles

Download subtitles or captions, including timestamped transcript files, without downloading the video

ytdlp_download_thumbnail

Download thumbnail, cover image, poster frame, or all thumbnails

ytdlp_download_playlist

Download playlist/channel entries with ranges, archive skipping, and max-download controls

Archive

Tool

What it does

ytdlp_inspect_archive

List saved entries in a yt-dlp download archive file

ytdlp_check_archive

Check if an exact yt-dlp archive entry is already present

ytdlp_update_archive

Plan archive handling and recommend download-archive usage; does not write the archive

Download + postprocess

Tool

What it does

ytdlp_remux

Download a URL and remux to a different container without re-encoding

ytdlp_recode

Download a URL and re-encode video to a target format

ytdlp_extract_audio

Download a URL and extract audio as mp3, m4a, opus, etc.

ytdlp_embed_assets

Download a URL and embed subtitles, thumbnails, metadata, or chapters

ytdlp_split_chapters

Download a URL and split media into one file per chapter

ytdlp_remove_chapters

Download a URL and remove chapters matching regex filters

ytdlp_apply_sponsorblock

Download a URL and remove or mark SponsorBlock segments

Expert

Tool

What it does

ytdlp_execute_expert

Last-resort raw yt-dlp argv escape hatch; requires YTDLP_MCP_ENABLE_EXPERT=true


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

spawn with argv arrays, shell: false — no shell injection possible

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 YTDLP_MCP_ALLOW_CONFIG_FILES=true or server-level env

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

YTDLP_MCP_OUTPUT_ROOT

~/Downloads/yt-dlp-mcp

Managed output directory

YTDLP_MCP_TEMP_ROOT

OS temp + yt-dlp-mcp

Managed temp directory

YTDLP_MCP_YTDLP_PATH

auto-detected

Override yt-dlp binary path

YTDLP_MCP_FFMPEG_PATH

auto-detected

Override ffmpeg binary path

YTDLP_MCP_FFPROBE_PATH

auto-detected

Override ffprobe binary path

YTDLP_MCP_ENABLE_EXPERT

false

Enable ytdlp_execute_expert

YTDLP_MCP_ALLOW_ARBITRARY_OUTPUT_PATHS

false

Allow paths outside managed roots

YTDLP_MCP_ALLOW_CONFIG_FILES

false

Allow cookie/netrc/config file inputs

YTDLP_MCP_COOKIES_FILE

—

Server-approved cookies file

YTDLP_MCP_COOKIES_FROM_BROWSER

—

Server-approved browser cookie source

YTDLP_MCP_TIMEOUT_MS

900000 (15 min)

Per-command timeout

YTDLP_MCP_MAX_OUTPUT_BYTES

4194304 (4 MiB)

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 explicitly

Supported --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

ytdlp://capabilities

Tool inventory and capability summary

Resource

ytdlp://option-catalog/groups

Full 323-option catalog by group

Resource

ytdlp://safety-policy

Current safety policy settings

Resource

ytdlp://troubleshooting

Common errors and fixes

Resource

ytdlp://environment

Live environment check snapshot

Prompt

archive_playlist_safely

Guided workflow for archive-protected playlist downloads

Prompt

choose_smallest_acceptable_format

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 tests

MCP Inspector for manual UX check:

npx -y @modelcontextprotocol/inspector node dist/index.js

License

MIT — see LICENSE.

Available Tools

28 tools
ytdlp_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 ArchiveA
Read-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 EnvironmentA
Read-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 ExpertA
Destructive

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 MetadataB
Read-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 ArchiveB
Read-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 ExtractorsA
Read-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 FormatsA
Read-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 TargetsA
Read-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 SubtitlesA
Read-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 ThumbnailsB
Read-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 DownloadA
Read-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 PostprocessA
Read-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 UrlA
Read-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 VideosA
Read-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 ArchiveA
Read-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 OptionsA
Read-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

    A4/5.0

    Scored across 28 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness5/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers