# 🎬 yt-dlp-mcp

**A powerful MCP server that brings video platform capabilities to your AI agents** [![npm version](https://img.shields.io/npm/v/@kevinwatt/yt-dlp-mcp.svg)](https://www.npmjs.com/package/@kevinwatt/yt-dlp-mcp) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Node.js Version](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org/) [![TypeScript](https://img.shields.io/badge/TypeScript-5.6-blue)](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)

--- ## ✨ Features

### 🔍 **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

### 🎥 **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

--- ## 🚀 Installation ### Prerequisites **Install yt-dlp** on your system:

Platform	Command
🪟 Windows	`winget install yt-dlp`
🍎 macOS	`brew install yt-dlp`
🐧 Linux	`pip install yt-dlp`

### 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

Dive

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!

Claude Code

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

Claude Desktop

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"] } } } ```

Cursor

Go to `Cursor Settings` -> `MCP` -> `New MCP Server`. Use the config provided above.

VS Code / Copilot

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.

Windsurf

Follow the [configure MCP guide](https://docs.windsurf.com/windsurf/cascade/mcp#mcp-config-json) using the standard config from above.

Cline

Follow [Cline MCP configuration guide](https://docs.cline.bot/mcp/configuring-mcp-servers) and use the config provided above.

Warp

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.

JetBrains AI Assistant

Go to `Settings | Tools | AI Assistant | Model Context Protocol (MCP)` -> `Add`. Use the config provided above.

### 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

Tool	Description
`ytdlp_search_videos`	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

### 📝 Subtitles & Transcripts

Tool	Description
`ytdlp_list_subtitle_languages`	List all available subtitle languages for a video - Parameters: `url` - Returns: Available languages, formats, auto-generated status
`ytdlp_download_video_subtitles`	Download subtitles in VTT format with timestamps - Parameters: `url`, `language` (optional) - Returns: Raw VTT subtitle content
`ytdlp_download_transcript`	Generate clean plain text transcript - Parameters: `url`, `language` (optional) - Returns: Cleaned text without timestamps or formatting

### 🎥 Video & Audio Downloads

Tool	Description
`ytdlp_download_video`	Download video to Downloads folder - Parameters: `url`, `resolution`, `startTime`, `endTime` - Resolutions: 480p, 720p, 1080p, best - Supports: Video trimming
`ytdlp_download_audio`	Extract and download audio only - Parameters: `url` - Format: Best quality M4A/MP3

### 📊 Metadata

Tool	Description
`ytdlp_get_video_metadata`	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.
`ytdlp_get_video_metadata_summary`	Get human-readable metadata summary - Parameters: `url` - Returns: Formatted text with key information

--- ## 💡 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" ``` ### 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 # Character limit (default: 25000) YTDLP_CHARACTER_LIMIT=25000 # Max transcript length (default: 50000) YTDLP_MAX_TRANSCRIPT_LENGTH=50000 ``` ### 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://... ``` --- ## 🔒 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 ---

[⬆ Back to Top](#-yt-dlp-mcp)

Yt Dlp Mcp

Install

Yt Dlp Mcp

Install