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

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