🎬 yt-dlp-mcp

A powerful MCP server that brings video platform capabilities to your AI agents

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 • Installation • Tools • Usage • 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:

{
  "mcpServers": {
    "yt-dlp": {
      "command": "npx",
      "args": ["-y", "@kevinwatt/yt-dlp-mcp@latest"]
    }
  }
}

MCP Client Configuration

Dive

Open Dive Desktop
Click "+ Add MCP Server"
Paste the config provided above
Click "Save" and you're ready!

Claude Code

Use the Claude Code CLI to add the yt-dlp MCP server (guide):

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

{
  "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:

code --add-mcp '{"name":"yt-dlp","command":"npx","args":["-y","@kevinwatt/yt-dlp-mcp@latest"]}'

Or follow the MCP install guide with the standard config from above.

Windsurf

Follow the configure MCP guide using the standard config from above.

Cline

Follow Cline MCP configuration guide and use the config provided above.

Warp

Go to Settings | AI | Manage MCP Servers -> + Add to add 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

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 - Detailed tool documentation
Configuration - Environment variables and settings
Cookie Configuration - Authentication and private video access
Error Handling - Common errors and solutions
Contributing - How to contribute

🔧 Configuration

Environment Variables

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

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

{
  "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 for detailed setup instructions.

🏗️ Architecture

Built With

yt-dlp - Video extraction engine
MCP SDK - Model Context Protocol
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:

{
  "total": 50,
  "count": 10,
  "offset": 0,
  "videos": [...],
  "has_more": true,
  "next_offset": 10
}

Markdown Format

Human-readable display:

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.

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

yt-dlp - The amazing video extraction tool
Anthropic - For the Model Context Protocol
Dive - MCP-compatible AI platform

📚 Related Projects

MCP Servers - Official MCP server implementations
yt-dlp - Command-line video downloader
Dive Desktop - AI agent platform

⬆ Back to Top

Name		Name	Last commit message	Last commit date
Latest commit History 83 Commits
.claude/skills/mcp-builder		.claude/skills/mcp-builder
docs		docs
src		src
tests		tests
.gitignore		.gitignore
.npmignore		.npmignore
.prettierrc		.prettierrc
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
eslint.config.mjs		eslint.config.mjs
jest.config.mjs		jest.config.mjs
package-lock.json		package-lock.json
package.json		package.json
tsconfig.jest.json		tsconfig.jest.json
tsconfig.json		tsconfig.json

License

kevinwatt/yt-dlp-mcp

Folders and files

Latest commit

History

Repository files navigation

🎬 yt-dlp-mcp

✨ Features

🔍 Search & Discovery

📊 Metadata Extraction

📝 Transcript & Subtitles

🎥 Video Downloads

🎵 Audio Extraction

🛡️ Privacy & Safety

🚀 Installation

Prerequisites

Getting Started

MCP Client Configuration

Manual Installation

🛠️ Available Tools

🔍 Search & Discovery

📝 Subtitles & Transcripts

🎥 Video & Audio Downloads

📊 Metadata

💡 Usage Examples

Search Videos

Get Metadata

Download Subtitles & Transcripts

Download Content

📖 Documentation

🔧 Configuration

Environment Variables

Cookie Configuration

🏗️ Architecture

Built With

Key Features

📊 Response Formats

JSON Format

Markdown Format

🔒 Privacy & Security

🤝 Contributing

📝 License

🙏 Acknowledgments

📚 Related Projects

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 3

Packages 0

Uh oh!

Contributors 6

Uh oh!

Languages

Packages