# yt-dlp-mcp

A tiny standalone [MCP](https://modelcontextprotocol.io) server that wraps
[yt-dlp](https://github.com/yt-dlp/yt-dlp) so any MCP-compatible client —
Claude Desktop, Claude Code, [HomeBot](https://github.com/kingithegreat/Sadie),
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](https://github.com/yt-dlp/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:

```json
{
  "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

```bash
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