yt-dlp

The yt-dlp-mcp tool acts as a bridge between AI assistants and the vast world of online video content. It allows AI agents to interact directly with platforms like YouTube, TikTok, and Facebook to perform tasks that would normally require manual browsing. Using simple natural language commands, a user can ask their AI to find specific tutorials, summarize the contents of a video via its transcript, or even download audio for a podcast—all without ever leaving the chat interface. Beyond simple downloads, this server provides robust discovery and extraction features that make video content more accessible to machines. It can search for videos with precise pagination, pull detailed metadata like view counts and upload dates, and generate clean, human-readable text transcripts from available subtitles. For those needing specific media, it supports high-quality audio extraction and video downloads at various resolutions, including the ability to trim specific segments from a longer clip. For developers and engineers, this MCP is specifically optimized for the constraints of Large Language Models. It utilizes Zod schema validation to ensure input safety and implements automatic character limits to prevent context window overflow, which is a common challenge when handling long transcripts or large metadata sets. By offering data in both structured JSON for programmatic tasks and Markdown for human-readable display, the server becomes a highly versatile component for building sophisticated, video-aware AI applications that are both safe and efficient.

1. Installation

Prerequisites
You must have yt-dlp installed on your system.

Manual Installation
You can install the package globally using npm:

npm install -g @kevinwatt/yt-dlp-mcp

2. Configuration

To use this server with an MCP-compatible client (like Claude Desktop, Dive, or Cursor), add the following to your configuration file:

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

Optional Environment Variables
You can customize the server behavior by setting these environment variables:
* YTDLP_DOWNLOADS_DIR: Path to downloads (default: ~/Downloads)
* YTDLP_DEFAULT_RESOLUTION: Default video quality (default: 720p)
* YTDLP_DEFAULT_SUBTITLE_LANG: Default language (default: en)
* YTDLP_CHARACTER_LIMIT: Limit for LLM safety (default: 25000)
* YTDLP_MAX_TRANSCRIPT_LENGTH: Max length for transcripts (default: 50000)

3. Available Tools

All tools are prefixed with ytdlp_ to avoid naming conflicts.

• ytdlp_search: Search YouTube with pagination.
  • Parameters: query, maxResults, offset, response_format (JSON or Markdown).
• ytdlp_list_subtitles: List all available subtitle languages for a video.
  • Parameters: url.
• ytdlp_download_subtitles: Download subtitles in VTT format.
  • Parameters: url, language (optional).
• ytdlp_get_transcript: Generate a clean plain text transcript.
  • Parameters: url, language (optional).
• ytdlp_download_video: Download video to the Downloads folder.
  • Parameters: url, resolution (480p, 720p, 1080p, best), startTime, endTime.
• ytdlp_download_audio: Extract and download audio only (M4A/MP3).
  • Parameters: url.
• ytdlp_get_metadata: Extract comprehensive video metadata in JSON.
  • Parameters: url, fields (optional array).
• ytdlp_get_metadata_summary: Get a human-readable metadata summary.
  • Parameters: url.

4. Example Prompts

• "Search for Python programming tutorials"
• "Find the top 20 machine learning videos"
• "Get metadata for https://youtube.com/watch?v=..."
• "Show me the title, channel, and view count for this video"
• "List available subtitles for https://youtube.com/watch?v=..."
• "Get a clean transcript of this video in Spanish"
• "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"

Use Case 1: Rapid Video Content Summarization and Research

Problem: Researching information within long-form video content (like 2-hour webinars or technical lectures) is time-consuming because users have to watch the entire video to find specific insights.
Solution: This MCP allows an AI agent to fetch clean, plain-text transcripts of videos without the user needing to leave the chat. The agent can then process the text to provide summaries, answer specific questions about the content, or extract key timestamps.
Example: "Get a clean transcript of this 90-minute keynote [URL] and summarize the three main product announcements mentioned in the middle of the video."

Use Case 2: Curating Educational Content for Offline Learning

Problem: Students or professionals often want to listen to video tutorials or talks as podcasts during commutes, but streaming high-definition video consumes significant data and battery.
Solution: Users can use natural language to find relevant educational videos and then specifically extract only the audio or a lower-resolution video version for offline use.
Example: "Search for the top 5 most relevant videos on 'Advanced Machine Learning' and download the audio-only versions of the first three results to my Downloads folder."

Use Case 3: Precise Video Clipping for Presentations or Social Media

Problem: Content creators or researchers often need a very specific segment of a long video (e.g., a 30-second demonstration) but don't want to download a massive 4GB file and use external editing software to trim it.
Solution: Using the video trimming support within the ytdlp_download_video tool, users can specify exact start and end times, allowing the AI to download only the necessary clip in the desired resolution.
Example: "I need the segment from 12:45 to 13:15 of this YouTube video [URL]. Download it in 1080p so I can include it in my presentation."

Use Case 4: Competitive Market Analysis for Content Creators

Problem: Marketers and YouTubers need to analyze the metadata (tags, categories, and upload patterns) of successful videos in their niche to optimize their own SEO, but manually copying this data is tedious.
Solution: The MCP can extract comprehensive metadata in structured JSON format. An AI agent can then analyze this data across multiple videos to identify trends in keywords, upload frequency, and engagement metrics.
Example: "Search for the top 10 trending videos about 'Mechanical Keyboards' and give me a summary of the most common tags and categories they use, formatted as a table."

Use Case 5: Multi-Language Accessibility and Translation

Problem: Global teams or language learners often need to access content in different languages, but auto-generated captions can be difficult to read or process when formatted with timestamps.
Solution: The MCP provides tools to list all available subtitle languages and download them as clean text. This allows users to quickly translate transcripts or create study guides in their native language.
Example: "Check if this video has Spanish subtitles. If it does, download the clean transcript in Spanish so I can review the terminology used."