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.

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