yt-dlp-mcp
A Model Context Protocol (MCP) server that bridges Video & Audio content with Large Language Models using yt-dlp.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/kevinwatt--yt-dlp-mcp)HTML
<a href="/listings/kevinwatt--yt-dlp-mcp"><img src="/api/listings/kevinwatt--yt-dlp-mcp/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Prerequisites
**Install yt-dlp** on your system:
<table> <tr> <th>Platform</th> <th>Command</th> </tr> <tr> <td>πͺ <strong>Windows</strong></td> <td><code>winget install yt-dlp</code></td> </tr> <tr> <td>π <strong>macOS</strong></td> <td><code>brew install yt-dlp</code></td> </tr> <tr> <td>π§ <strong>Linux</strong></td> <td><code>pip install yt-dlp</code></td> </tr> </table>
Getting Started
Add the following config to your MCP client:
{
"mcpServers": {
"yt-dlp": {
"command": "npx",
"args": ["-y", "@kevinwatt/yt-dlp-mcp@latest"]
}
}
}MCP Client Configuration
<details open> <summary><strong>Dive</strong></summary>
1. Open [Dive Desktop](https://github.com/OpenAgentPlatform/Dive) 2. Click **"+ Add MCP Server"** 3. Paste the config provided above 4. Click **"Save"** and you're ready!
</details>
<details> <summary><strong>Claude Code</strong></summary>
Use the Claude Code CLI to add the yt-dlp MCP server ([guide](https://docs.anthropic.com/en/docs/claude-code/mcp)):
claude mcp add yt-dlp npx @kevinwatt/yt-dlp-mcp@latest
</details>
<details> <summary><strong>Claude Desktop</strong></summary>
Add to your `claude_desktop_config.json`:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` - Windows: `%APPDATA%\Claude\claude_desktop_config.json` - Linux: `~/.config/Claude/claude_desktop_config.json`
{
"mcpServers": {
"yt-dlp": {
"command": "npx",
"args": ["-y", "@kevinwatt/yt-dlp-mcp@latest"]
}
}
}</details>
<details> <summary><strong>Cursor</strong></summary>
Go to `Cursor Settings` -> `MCP` -> `New MCP Server`. Use the config provided above.
</details>
<details> <summary><strong>VS Code / Copilot</strong></summary>
Install via the VS Code CLI:
code --add-mcp '{"name":"yt-dlp","command":"npx","args":["-y","@kevinwatt/yt-dlp-mcp@latest"]}'Or follow the [MCP install guide](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server) with the standard config from above.
</details>
<details> <summary><strong>Windsurf</strong></summary>
Follow the [configure MCP guide](https://docs.windsurf.com/windsurf/cascade/mcp#mcp-config-json) using the standard config from above.
</details>
<details> <summary><strong>Cline</strong></summary>
Follow [Cline MCP configuration guide](https://docs.cline.bot/mcp/configuring-mcp-servers) and use the config provided above.
</details>
<details> <summary><strong>Warp</strong></summary>
Go to `Settings | AI | Manage MCP Servers` -> `+ Add` to [add an MCP Server](https://docs.warp.dev/knowledge-and-collaboration/mcp#adding-an-mcp-server). Use the config provided above.
</details>
<details> <summary><strong>JetBrains AI Assistant</strong></summary>
Go to `Settings | Tools | AI Assistant | Model Context Protocol (MCP)` -> `Add`. Use the config provided above.
</details>
Manual Installation
npm install -g @kevinwatt/yt-dlp-mcp
---
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md Β· README Β· 684 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- # π¬ yt-dlp-mcp
- <div align="center">
- **A powerful MCP server that brings video platform capabilities to your AI agents**
- [](https://www.npmjs.com/package/@kevinwatt/yt-dlp-mcp)
- [](https://opensource.org/licenses/MIT)
- [](https://nodejs.org/)
- [](https://www.typescriptlang.org/)
- Integrate yt-dlp with Claude, Dive, and other MCP-compatible AI systems. Download videos, extract metadata, get transcripts, and more β all through natural language.
- [Features](#-features) β’ [Installation](#-installation) β’ [Tools](#-available-tools) β’ [Usage](#-usage-examples) β’ [Documentation](#-documentation)
- </div>
- ---
- ## β¨ Features
- <table>
- <tr>
- <td width="50%">
- ### π **Search & Discovery**
- - Search YouTube with pagination
- - JSON or Markdown output formats
- - Filter by relevance and quality
- ### π **Metadata Extraction**
- - Comprehensive video information
- - Channel details and statistics
- - Upload dates, tags, categories
- - No content download required
- ### π **Transcript & Subtitles**
- - Download subtitles in VTT format
- - Generate clean text transcripts
- - Multi-language support
- - Auto-generated captions
- </td>
- <td width="50%">
- ### π₯ **Video Downloads**
- - Resolution control (480p-1080p)
- - Video trimming support
- - Platform-agnostic (YouTube, Facebook, etc.)
- - Saved to Downloads folder
- ### π΅ **Audio Extraction**
- - Best quality audio (M4A/MP3)
- - Direct audio-only downloads
- - Perfect for podcasts & music
- ### π‘οΈ **Privacy & Safety**
- - No tracking or analytics
- - Direct downloads via yt-dlp
- - Zod schema validation
- - Character limits for LLM safety
- </td>
- </tr>
- </table>
- ---
- ## π Installation
- ### Prerequisites
- **Install yt-dlp** on your system:
- <table>
- <tr>
- <th>Platform</th>
- <th>Command</th>
- </tr>
- <tr>
- <td>πͺ <strong>Windows</strong></td>
- <td><code>winget install yt-dlp</code></td>
- </tr>
- <tr>
- <td>π <strong>macOS</strong></td>
- <td><code>brew install yt-dlp</code></td>
- </tr>
- <tr>
- <td>π§ <strong>Linux</strong></td>
- <td><code>pip install yt-dlp</code></td>
- </tr>
- </table>
- ### Getting Started
- Add the following config to your MCP client:
- ```json
- {
- "mcpServers": {
- "yt-dlp": {
- "command": "npx",
- "args": ["-y", "@kevinwatt/yt-dlp-mcp@latest"]
- }
- }
- }
- ```
- ### MCP Client Configuration
- <details open>
- <summary><strong>Dive</strong></summary>
- 1. Open [Dive Desktop](https://github.com/OpenAgentPlatform/Dive)
- 2. Click **"+ Add MCP Server"**
- 3. Paste the config provided above
- 4. Click **"Save"** and you're ready!
- </details>
- <details>
- <summary><strong>Claude Code</strong></summary>
- Use the Claude Code CLI to add the yt-dlp MCP server ([guide](https://docs.anthropic.com/en/docs/claude-code/mcp)):
- ```bash
- claude mcp add yt-dlp npx @kevinwatt/yt-dlp-mcp@latest
- ```
- </details>
- <details>
- <summary><strong>Claude Desktop</strong></summary>
- Add to your `claude_desktop_config.json`:
- - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- - Linux: `~/.config/Claude/claude_desktop_config.json`
- ```json
- {
- "mcpServers": {
- "yt-dlp": {
- "command": "npx",
- "args": ["-y", "@kevinwatt/yt-dlp-mcp@latest"]
- }
- }
- }
- ```
- </details>
- <details>
- <summary><strong>Cursor</strong></summary>
- Go to `Cursor Settings` -> `MCP` -> `New MCP Server`. Use the config provided above.
- </details>
- <details>
- <summary><strong>VS Code / Copilot</strong></summary>
- Install via the VS Code CLI:
- ```bash
- code --add-mcp '{"name":"yt-dlp","command":"npx","args":["-y","@kevinwatt/yt-dlp-mcp@latest"]}'
- ```
- Or follow the [MCP install guide](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server) with the standard config from above.
- </details>
- <details>
- <summary><strong>Windsurf</strong></summary>
- Follow the [configure MCP guide](https://docs.windsurf.com/windsurf/cascade/mcp#mcp-config-json) using the standard config from above.
- </details>
- <details>
- <summary><strong>Cline</strong></summary>
- Follow [Cline MCP configuration guide](https://docs.cline.bot/mcp/configuring-mcp-servers) and use the config provided above.
- </details>
- <details>
- <summary><strong>Warp</strong></summary>
- Go to `Settings | AI | Manage MCP Servers` -> `+ Add` to [add an MCP Server](https://docs.warp.dev/knowledge-and-collaboration/mcp#adding-an-mcp-server). Use the config provided above.
- </details>
- <details>
- <summary><strong>JetBrains AI Assistant</strong></summary>
- Go to `Settings | Tools | AI Assistant | Model Context Protocol (MCP)` -> `Add`. Use the config provided above.
- </details>
- ### Manual Installation
- ```bash
- npm install -g @kevinwatt/yt-dlp-mcp
- ```
- ---
- ## π οΈ Available Tools
- All tools are prefixed with `ytdlp_` to avoid naming conflicts with other MCP servers.
- ### π Search & Discovery
- <table>
- <tr>
- <th width="30%">Tool</th>
- <th width="70%">Description</th>
- </tr>
- <tr>
- <td><code>ytdlp_search_videos</code></td>
- <td>
- Search YouTube with pagination and date filtering support
- - **Parameters**: `query`, `maxResults`, `offset`, `response_format`, `uploadDateFilter`
- - **Date Filter**: `hour`, `today`, `week`, `month`, `year` (optional)
- - **Returns**: Video list with titles, channels, durations, URLs
- - **Supports**: JSON and Markdown formats
- </td>
- </tr>
- </table>
- ### π Subtitles & Transcripts
- <table>
- <tr>
- <th width="30%">Tool</th>
- <th width="70%">Description</th>
- </tr>
- <tr>
- <td><code>ytdlp_list_subtitle_languages</code></td>
- <td>
- List all available subtitle languages for a video
- - **Parameters**: `url`
- - **Returns**: Available languages, formats, auto-generated status
- </td>
- </tr>
- <tr>
- <td><code>ytdlp_download_video_subtitles</code></td>
- <td>
- Download subtitles in VTT format with timestamps
- - **Parameters**: `url`, `language` (optional)
- - **Returns**: Raw VTT subtitle content
- </td>
- </tr>
- <tr>
- <td><code>ytdlp_download_transcript</code></td>
- <td>
- Generate clean plain text transcript
- - **Parameters**: `url`, `language` (optional)
- - **Returns**: Cleaned text without timestamps or formatting
- </td>
- </tr>
- </table>
- ### π₯ Video & Audio Downloads
- <table>
- <tr>
- <th width="30%">Tool</th>
- <th width="70%">Description</th>
- </tr>
- <tr>
- <td><code>ytdlp_download_video</code></td>
- <td>
- Download video to Downloads folder
- - **Parameters**: `url`, `resolution`, `startTime`, `endTime`
- - **Resolutions**: 480p, 720p, 1080p, best
- - **Supports**: Video trimming
- </td>
- </tr>
- <tr>
- <td><code>ytdlp_download_audio</code></td>
- <td>
- Extract and download audio only
- - **Parameters**: `url`
- - **Format**: Best quality M4A/MP3
- </td>
- </tr>
- </table>
- ### π Metadata
- <table>
- <tr>
- <th width="30%">Tool</th>
- <th width="70%">Description</th>
- </tr>
- <tr>
- <td><code>ytdlp_get_video_metadata</code></td>
- <td>
- Extract comprehensive video metadata in JSON
- - **Parameters**: `url`, `fields` (optional array)
- - **Returns**: Complete metadata or filtered fields
- - **Includes**: Views, likes, upload date, tags, formats, etc.
- </td>
- </tr>
- <tr>
- <td><code>ytdlp_get_video_metadata_summary</code></td>
- <td>
- Get human-readable metadata summary
- - **Parameters**: `url`
- - **Returns**: Formatted text with key information
- </td>
- </tr>
- </table>
- ### π¬ Comments
- <table>
- <tr>
- <th width="30%">Tool</th>
- <th width="70%">Description</th>
- </tr>
- <tr>
- <td><code>ytdlp_get_video_comments</code></td>
- <td>
- Extract comments in flat JSON, threaded JSON, or AI-friendly Markdown
- - **Parameters**: `url`, `maxComments`, `sortOrder`, `view`, `responseFormat`, `maxParents`, `maxReplies`, `maxRepliesPerThread`, `maxDepth`
- - **Views**: `flat` (default) or `threaded`
- - **Formats**: `json` (default) or `markdown_tree` (`markdown_tree` requires threaded view)
- - **Returns**: Comment objects with `depth`, `reply_count`, `root_threads`, `reply_comments`, `orphan_comments`
- - **Graceful Degradation**: On platforms without parent metadata, threaded mode falls back to root-only comments
- </td>
- </tr>
- <tr>
- <td><code>ytdlp_get_video_comments_summary</code></td>
- <td>
- Get a human-readable summary of comments
- - **Parameters**: `url`, `maxComments`, `view`
- - **Views**: `flat` (linear summary) or `threaded` (grouped reply trees)
- - **Returns**: Readable comment digest with author badges, time, likes, and grouped replies
- </td>
- </tr>
- </table>
- ---
- ## π‘ Usage Examples
- ### Search Videos
- ```
- "Search for Python programming tutorials"
- "Find the top 20 machine learning videos"
- "Search for 'react hooks tutorial' and show results 10-20"
- "Search for JavaScript courses in JSON format"
- ```
- ### Get Metadata
- ```
- "Get metadata for https://youtube.com/watch?v=..."
- "Show me the title, channel, and view count for this video"
- "Extract just the duration and upload date"
- "Give me a quick summary of this video's info"
- ```
- ### Get Comments
- ```
- "Get the top 20 comments for https://youtube.com/watch?v=..."
- "Get comments as threaded JSON for this video"
- "Extract comments as markdown_tree so the reply branches stay intact"
- "Get newest comments with maxDepth 1 and maxRepliesPerThread 0"
- "Summarize comments in threaded view"
- ```
- ### Download Subtitles & Transcripts
- ```
- "List available subtitles for https://youtube.com/watch?v=..."
- "Download English subtitles from this video"
- "Get a clean transcript of this video in Spanish"
- "Download Chinese (zh-Hant) transcript"
- ```
- ### Download Content
- ```
- "Download this video in 1080p: https://youtube.com/watch?v=..."
- "Download audio from this YouTube video"
- "Download this video from 1:30 to 2:45"
- "Save this Facebook video to my Downloads"
- ```
- ---
- ## π Documentation
- - **[API Reference](./docs/api.md)** - Detailed tool documentation
- - **[Configuration](./docs/configuration.md)** - Environment variables and settings
- - **[Cookie Configuration](./docs/cookies.md)** - Authentication and private video access
- - **[Error Handling](./docs/error-handling.md)** - Common errors and solutions
- - **[Contributing](./docs/contributing.md)** - How to contribute
- ---
- ## π§ Configuration
- ### Environment Variables
- ```bash
- # Downloads directory (default: ~/Downloads)
- YTDLP_DOWNLOADS_DIR=/path/to/downloads
- # Default resolution (default: 720p)
- YTDLP_DEFAULT_RESOLUTION=1080p
- # Default subtitle language (default: en)
- YTDLP_DEFAULT_SUBTITLE_LANG=en
- # Allow URLs that resolve to localhost/private/link-local addresses (default: false)
- YTDLP_ALLOW_PRIVATE_URLS=false
- ```
- Only `http`/`https` URLs are accepted, and URLs whose host resolves to a loopback, private, or link-local address (e.g. `localhost`, `192.168.x.x`, `169.254.169.254`) are rejected. Set `YTDLP_ALLOW_PRIVATE_URLS=true` if you need to fetch media from your local network.
- > **Limitation:** this check runs once on the URL you pass in, before yt-dlp starts. yt-dlp then makes its own connections, so it does **not** cover HTTP redirects to internal addresses or DNS rebinding. If you run this server where reaching internal services matters (e.g. a shared or cloud-hosted deployment), restrict outbound traffic at the network layer (container network policy, firewall, or blocking `169.254.169.254`).
- See the [Configuration Guide](./docs/configuration.md) for the full list.
- ### Proxy and yt-dlp Config File
- All tools read your yt-dlp config file (`~/.config/yt-dlp/config`), so any
- `--proxy`, `--cookies` or other options set there apply automatically. This is
- the only channel available to MCP clients that cannot pass environment
- variables to the server process.
- These are alternatives β set only the one you need:
- | Setting | Effect |
- |---------|--------|
- | `YTDLP_PROXY=socks5://127.0.0.1:1080` | Route all requests through this proxy |
- | `YTDLP_PROXY=` (empty) | Force a direct connection, overriding a proxy in the yt-dlp config file |
- | `YTDLP_IGNORE_CONFIG=1` | Skip all yt-dlp config files |
- Supported proxy schemes: `http`, `https`, `socks4`, `socks5`, `socks5h`.
- > `YTDLP_IGNORE_CONFIG=1` is not a straight revert to 0.9.x. The search,
- > metadata and comments tools always read the config file, so this setting
- > stops them from doing so as well.
- **MCP Configuration with a proxy:**
- ```json
- {
- "mcpServers": {
- "yt-dlp": {
- "command": "npx",
- "args": ["-y", "@kevinwatt/yt-dlp-mcp@latest"],
- "env": {
- "YTDLP_PROXY": "socks5://127.0.0.1:1080"
- }
- }
- }
- }
- ```
- If your MCP client cannot pass environment variables to the server, put the
- options in `~/.config/yt-dlp/config` instead β every tool reads that file:
- ```
- --proxy socks5://127.0.0.1:1080
- --cookies /path/to/cookies.txt
- ```
- > **Note**: Your config file applies to downloads as well. Options that change
- > the output format (`-x`, `--remux-video`, `--recode-video`) change what the
- > download tools produce; the tools report the file yt-dlp actually wrote, so
- > the reported name stays correct. Output-location options (`-o`, `-P`) have no
- > effect, because the tools always pass an absolute `--output` on the command
- > line, which takes precedence.
- >
- > **Note**: yt-dlp config files can contain options that execute commands
- > (`--exec`, `--postprocessor-args`, `--ffmpeg-location`). These now run on
- > tool invocations too, including ones triggered by an AI assistant. Set
- > `YTDLP_IGNORE_CONFIG=1` if you would rather the server ignore your config
- > file entirely.
- ### Cookie Configuration
- To access private videos, age-restricted content, or avoid rate limits, configure cookies:
- > β οΈ **Important**: Cookie authentication requires a JavaScript runtime (deno) to be installed. When using cookies, YouTube uses authenticated API endpoints that require JavaScript challenge solving. Without deno, downloads will fail with "n challenge solving failed" error.
- >
- > Install deno: https://docs.deno.com/runtime/getting_started/installation/
- ```bash
- # Extract cookies from browser (recommended)
- YTDLP_COOKIES_FROM_BROWSER=chrome
- # Or use a cookie file
- YTDLP_COOKIES_FILE=/path/to/cookies.txt
- ```
- **MCP Configuration with cookies:**
- ```json
- {
- "mcpServers": {
- "yt-dlp": {
- "command": "npx",
- "args": ["-y", "@kevinwatt/yt-dlp-mcp@latest"],
- "env": {
- "YTDLP_COOKIES_FROM_BROWSER": "chrome"
- }
- }
- }
- }
- ```
- Supported browsers: `brave`, `chrome`, `chromium`, `edge`, `firefox`, `opera`, `safari`, `vivaldi`, `whale`
- See [Cookie Configuration Guide](./docs/cookies.md) for detailed setup instructions.
- ---
- ## ποΈ Architecture
- ### Built With
- - **[yt-dlp](https://github.com/yt-dlp/yt-dlp)** - Video extraction engine
- - **[MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk)** - Model Context Protocol
- - **[Zod](https://github.com/colinhacks/zod)** - TypeScript-first schema validation
- - **TypeScript** - Type safety and developer experience
- ### Key Features
- - β **Type-Safe**: Full TypeScript with strict mode
- - β **Validated Inputs**: Zod schemas for runtime validation
- - β **Character Limits**: Automatic truncation to prevent context overflow
- - β **Tool Annotations**: readOnly, destructive, idempotent hints
- - β **Error Guidance**: Actionable error messages for LLMs
- - β **Modular Design**: Clean separation of concerns
- ---
- ## π Response Formats
- ### JSON Format
- Perfect for programmatic processing:
- ```json
- {
- "total": 50,
- "count": 10,
- "offset": 0,
- "videos": [...],
- "has_more": true,
- "next_offset": 10
- }
- ```
- ### Markdown Format
- Human-readable display:
- ```markdown
- Found 50 videos (showing 10):
- 1. **Video Title**
- πΊ Channel: Creator Name
- β±οΈ Duration: 10:30
- π URL: https://...
- ```
- ### Comment Markdown Tree
- Useful for LLM analysis when reply context matters:
- ```markdown
- # AI-Ready Comment Threads
- source_title: "Sample Video"
- comments_detected: 20
- root_threads: 6
- reply_comments: 14
- ## Threads
- ### Thread 1
- - comment_id: "abc123"
- parent_id: "root"
- depth: 0
- reply_count: 2
- text:
- | Root comment text
- - comment_id: "reply456"
- parent_id: "abc123"
- depth: 1
- reply_count: 0
- text:
- | Reply text
- ```
- ### Comment Limits
- YouTube comment extraction supports the full extractor tuple:
- ```text
- youtube:comment_sort=<sort>;max_comments=<total>,<parents>,<replies>,<repliesPerThread>,<depth>
- ```
- Examples:
- - Default behavior: `maxComments=20` yields `max_comments=20,20,20,20,2`
- - Root-only comments: `maxDepth=1`, `maxRepliesPerThread=0`
- - Limited branching: `maxReplies=40`, `maxRepliesPerThread=5`, `maxDepth=2`
- ---
- ## π Privacy & Security
- - **No Tracking**: Direct downloads, no analytics
- - **Input Validation**: Zod schemas prevent injection
- - **URL Validation**: Strict URL format checking
- - **Character Limits**: Prevents context overflow attacks
- - **Read-Only by Default**: Most tools don't modify system state
- ---
- ## π€ Contributing
- Contributions are welcome! Please check out our [Contributing Guide](./docs/contributing.md).
- 1. Fork the repository
- 2. Create a feature branch (`git checkout -b feature/amazing-feature`)
- 3. Commit your changes (`git commit -m 'Add amazing feature'`)
- 4. Push to the branch (`git push origin feature/amazing-feature`)
- 5. Open a Pull Request
- ---
- ## π License
- This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
- ---
- ## π Acknowledgments
- - [yt-dlp](https://github.com/yt-dlp/yt-dlp) - The amazing video extraction tool
- - [Anthropic](https://www.anthropic.com/) - For the Model Context Protocol
- - [Dive](https://github.com/OpenAgentPlatform/Dive) - MCP-compatible AI platform
- ---
- ## π Related Projects
- - [MCP Servers](https://github.com/modelcontextprotocol/servers) - Official MCP server implementations
- - [yt-dlp](https://github.com/yt-dlp/yt-dlp) - Command-line video downloader
- - [Dive Desktop](https://github.com/OpenAgentPlatform/Dive) - AI agent platform
- ---
- <div align="center">
- [β¬ Back to Top](#-yt-dlp-mcp)
- </div>
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If itβs helped, pass it on.