yt-dlp-mcp-server

v0.1.1

Published

9 days ago

Production-grade MCP server that lets LLM agents inspect, plan, download, and postprocess media URLs with yt-dlp, including YouTube and youtu.be links. 28 typed tools, managed output roots, safe argv execution, full yt-dlp option catalog.

yt-dlp-mcp-server

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.

MCP server pre-release: v0.1.1 is ready for early users, but pin versions in production while the public release process stabilizes.

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 |

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 | sudo apt install -y nodejs 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 |

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.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

yt-dlp-mcp-server

Why This One

Quick Start

Step 1 — Install media tools

Step 2 — Add to your MCP client

Step 3 — Verify

Client Setup

Docker

Tools

Environment

Inspect (read-only, no file writes)

Agent routing

Plan (dry-run, explains before writing)

Download

Archive

Download + postprocess

Expert

Usage Examples

Search and discover

Inspect before committing

Download

Postprocess

Archive management

Safety Model

Environment Variables

CLI

Resources and Prompts

Development

License