Skip to main content
Glama
kingithegreat

yt-dlp-mcp

by kingithegreat
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

yt-dlp-mcp

A tiny standalone MCP server that wraps yt-dlp so any MCP-compatible client — Claude Desktop, Claude Code, HomeBot, or anything else — can look up video metadata and download videos.

Tools

Tool

Description

Confirmation

get_video_info

Title, uploader, duration, view count, thumbnail, available qualities. Read-only.

Not required

download_video

Downloads a video to ~/Downloads (or a chosen sub-folder). Quality: best / 1080p / 720p / 480p / audio_only. Refuses playlists unless allow_playlist is set.

Recommended — tool is annotated readOnlyHint: false so any host that respects MCP tool annotations should confirm before running it.

Related MCP server: MCP YouTube-DLP

Requirements

  • Node.js 18+

  • yt-dlp installed separately and on PATH:

    • Windows: winget install yt-dlp.yt-dlp

    • macOS: brew install yt-dlp

    • Any OS: pip install yt-dlp

This server does not bundle yt-dlp. If it's missing, both tools return a clear error telling the user how to install it instead of failing silently.

Using it from an MCP client

Point any MCP host at this repo with npx — no npm publish or local clone needed:

{
  "mcpServers": {
    "yt-dlp": {
      "command": "npx",
      "args": ["-y", "github:kingithegreat/yt-dlp-mcp"]
    }
  }
}

  • Claude Desktop / Claude Code: add the block above to your MCP config file.

  • HomeBot: add the same shape to your mcp-servers.json (type: "stdio", command: "npx", args: ["-y", "github:kingithegreat/yt-dlp-mcp"]).

Local development

npm install
npm run build     # compiles src/ -> dist/
npm test          # jest, mocks child_process — no real yt-dlp calls in CI
npm start          # run the server on stdio directly

Safety notes

  • All yt-dlp invocations use execFile with argv arrays — the URL is never interpolated into a shell string, so there's no shell-injection surface.

  • download_video writes are confined to the user's home directory (resolveOutputDir rejects anything that resolves outside of it).

  • Playlist URLs are refused by default (--no-playlist) unless allow_playlist is explicitly passed, to avoid an accidental mass-download.

  • A single download is capped at a 10-minute timeout.

License

MIT

Available Tools

2 tools
download_videoA

Download a video from a URL (YouTube and hundreds of other sites via yt-dlp) to disk. Saves into ~/Downloads by default. Refuses playlist URLs unless allow_playlist is set, to avoid downloading an entire playlist by accident. yt-dlp must be installed separately and reachable on PATH.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYesThe video URL to download.
qualityNoDesired quality/format. Defaults to "best".
output_dirNoFolder to save into, relative to home (e.g. "Downloads", "Downloads/clips"). Defaults to Downloads.
allow_playlistNoIf true and the URL is a playlist, download every video in it. Default false (single video only).

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Describes download destination ('Saves into ~/Downloads by default'), playlist refusal to avoid accidental full downloads, and required external tool. Adds context beyond annotations (readOnlyHint=false, destructiveHint=false).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Four sentences, each serving a distinct purpose: action and scope, default location, safety behavior, dependency. No redundant or vague statements.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers core behavior, defaults, playlist safeguard, and external dependency. No output schema needed; description is sufficient for an agent to use the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% (baseline 3). Description adds context for allow_playlist (refusal unless set) and output_dir (default ~/Downloads). Enhances understanding of parameter behavior beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states verb 'Download', resource 'video from a URL', and scope 'YouTube and hundreds of other sites via yt-dlp'. Distinguishes from sibling 'get_video_info' which retrieves info only.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides guidance on playlist handling ('Refuses playlist URLs unless allow_playlist is set') and dependency ('yt-dlp must be installed separately and reachable on PATH'). Implicitly differentiates from sibling by action (download vs info).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_video_infoA
Read-onlyIdempotent

Look up metadata for a video URL (YouTube and hundreds of other sites via yt-dlp) without downloading it. Returns title, uploader, duration, view count, thumbnail, and available video qualities. For playlist URLs, only the first video is inspected.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYesThe video URL to look up (e.g. a YouTube link).

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. Description adds specific return fields, confirms no download, and notes playlist behavior. No contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with core purpose, no fluff. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite no output schema, description lists key return fields. Covers playlist edge case. Adequate for a simple lookup tool with one parameter.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with a clear description for the single url parameter. Description adds minimal extra beyond the schema's example 'e.g. a YouTube link'. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clear verb (look up metadata) and resource (video URL). Explicitly states it does not download, distinguishing from sibling download_video. Mentions support for YouTube and hundreds of other sites via yt-dlp.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implies use for metadata inspection without downloading, and notes limitation for playlists (only first video). Does not explicitly say when not to use or name alternatives, but sibling tool name provides contrast.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 2 tool updatesv0.1.0
    • First observeddownload_video
    • First observedget_video_info
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.4/5.0
Disambiguation5/5

The two tools have completely distinct purposes—one retrieves metadata, the other downloads content—with no overlap in functionality.

Naming Consistency5/5

Both tool names follow a consistent verb_noun pattern (download_video, get_video_info), making them predictable and easy to distinguish.

Tool Count4/5

With only two tools, the set is minimal but sufficient for its core purpose of retrieving video info and downloading. A few more utility tools might enhance coverage, but the count is reasonable for a focused wrapper.

Completeness4/5

The tools cover the two primary actions (metadata retrieval and download) but lack features like format selection or playlist handling (only via flag). Gaps are minor given the scope.

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/kingithegreat/yt-dlp-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server