yt-dlp-mcp

Standalone MCP server for extracting metadata and downloading videos (TikTok, YouTube, etc.) via yt-dlp.

Features

• Extract video metadata (title, description, uploader, duration)

• Get direct .mp4 link without downloading

• Download videos locally to a downloads folder (now generates both universal MP4 and separate MP3 audio file)

• Clear downloads cache to free up disk space

• Support for multiple platforms (TikTok, YouTube, Facebook, Vimeo, etc.)

Related MCP server: YouTube Search & Download MCP Server

Installation

# Project initialization (already done)
uv init

# Install dependencies (already done)
uv add "mcp[cli]" yt-dlp

Usage

Start the server

uv run server.py

The server runs in stdio mode and is ready to be used by any MCP client.

Usage with various MCP clients

Cline /cline (VS Code)

Add to your ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json an entry to "mcpServers" element:

the above path is for macos, with cline installed as VS code extension ! you'll have to check for linux ou windows using the cline mcp configuration management interface, it opens the file for you ! with "Configure MCP Servers" Button !

{
  "mcpServers": {
    "other-mcp-server": { },
    "yt-dlp": {
      "command": "uv",
      "args": ["run", "--directory", "<your_path>/yt-dlp-mcp", "server.py"]
    }
  }
}

don't use ~ in , else cline won't find the file, use true root path !

OpenCode

Add to your ~/.opencode/mcp.json:

{
  "servers": {
    "yt-dlp": {
      "command": "uv",
      "args": ["run", "--directory", "<your_path>/yt-dlp-mcp", "server.py"]
    }
  }
}

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "yt-dlp": {
      "command": "uv",
      "args": ["run", "--directory", "<your_path>/yt-dlp-mcp", "server.py"]
    }
  }
}

Zed

Add to your ~/.config/zed/settings.json:

{
  "mcp": {
    "servers": {
      "yt-dlp": {
        "command": "uv",
        "args": ["run", "--directory", "<your_path>/yt-dlp-mcp", "server.py"]
      }
    }
  }
}

Cursor

Add to your ~/.cursor/mcp.json:

{
  "mcpServers": {
    "yt-dlp": {
      "command": "uv",
      "args": ["run", "--directory", "<your_path>/yt-dlp-mcp", "server.py"]
    }
  }
}

Available Tools

1. extract_video_info

Extracts metadata and direct link from a video. Supports Facebook via lightweight regex and fb-video scraper as fallback.

extract_video_info(url="https://www.tiktok.com/@username/video/123456789")

Parameters:

• url (str): The URL of the video to extract

Returns:

• title : Video title

• description : Video description

• uploader : Uploader name

• duration : Duration in seconds

• url : Direct video link (.mp4)

• webpage_url : Original page URL

• thumbnail : Thumbnail URL

• error : Error message if extraction failed

• source : Scraper source (if using Facebook fallbacks)

2. download_video

Downloads a video and generates both a universal MP4 (H.264/AAC/FastStart) and a separate MP3 audio file to the local downloads folder.

download_video(url="https://www.tiktok.com/@username/video/123456789")

Parameters:

• url (str): The URL of the video to download

Returns:

• success : Boolean indicating success

• title : Video title

• filename_mp4 : Local MP4 filename

• filename_mp3 : Local MP3 filename

• local_path_mp4 : Absolute path to the downloaded MP4 file

• local_path_mp3 : Absolute path to the downloaded MP3 file

• message : Status message

• error : Error message if download failed

3. clear_downloads

Clears all files from the downloads folder.

clear_downloads()

Returns:

• success : Boolean indicating success

• deleted_count : Number of files deleted

• error : Error message if operation failed

Updating dependencies

uv add --upgrade yt-dlp

Requirements

• Python 3.10+

• uv (Python package manager)

• ffmpeg (optional, for video processing)