Skip to main content
Glama

Video Downloader MCP Server

by chazmaniandinkle
GitHub
Python
MIT License
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

๐ŸŽฌ Video Downloader MCP Server

License: MIT Python 3.8+ MCP Compatible

Give your agents the ability to download videos from 1000+ sites with built-in security. This MCP server provides 7 discrete tools that agents can use to check, analyze, and download videos from nearly any web page. Built on yt-dlp with security validation and fallback analysis.

๐ŸŒŸ Features

  • ๐Ÿ› ๏ธ 7 MCP Tools - Discrete capabilities for checking, analyzing, and downloading videos

  • ๐Ÿ”’ Built-in Security - Path validation, location restrictions, and input sanitization

  • ๐ŸŒ 1000+ Sites Supported - YouTube, Facebook, TikTok, and hundreds more via yt-dlp

  • ๐Ÿ”„ Fallback Analysis - Pattern matching when yt-dlp doesn't support a site

  • ๐Ÿ“ Organized Downloads - Configurable secure locations with filename templates

  • โš™๏ธ Agent-Friendly - Clean JSON responses and structured error handling

๐Ÿš€ Quick Start

Installation

# Install dependencies pip install mcp yt-dlp requests aiohttp # For Python < 3.11, also install: pip install tomli # Clone the repository git clone https://github.com/chazmaniandinkle/video-downloader-mcp.git cd video-downloader-mcp

Configuration

Add to your MCP client configuration (e.g., Claude Desktop):

{ "mcpServers": { "video-downloader": { "command": "python", "args": ["/path/to/video-downloader-mcp/server.py"] } } }

First Download

Your agent can now download videos with simple tool calls:

# Agent workflow example 1. check_ytdlp_support("https://youtube.com/watch?v=example") # โ†’ supported: true 2. get_video_formats(url) # โ†’ analyze available qualities 3. download_video(url, location_id="default", format_id="best") # โ†’ download to ~/video-downloader/

๐Ÿ› ๏ธ Available Tools

Tool

Purpose

Example Usage

check_ytdlp_support

Quick URL validation

"Is this video URL supported?"

get_video_info

Extract metadata

"What's the video duration and quality?"

get_video_formats

List quality options

"What download formats are available?"

download_video

Secure download

"Download this video in 1080p"

get_download_locations

Show safe locations

"Where can I save downloaded files?"

analyze_webpage

Fallback analysis

"yt-dlp failed, analyze the page"

extract_media_patterns

Pattern matching

"Find video URLs in this HTML"

๐Ÿ”’ Security Features

Built-in Protection

  • Path Traversal Prevention - Blocks ../ directory escape attempts

  • Location Restrictions - Downloads only to configured safe directories

  • Extension Validation - Allows only safe file types (video/audio/subtitles)

  • Template Sanitization - Removes dangerous shell characters

  • TOML Configuration - No deserialization vulnerabilities

Secure Download Example

{ "url": "https://example.com/video", "location_id": "default", // Uses configured secure location "relative_path": "movies/action", // Validated relative path "filename_template": "%(title)s.%(ext)s" // Sanitized template }

Default Security Configuration

[security] enforce_location_restrictions = true max_filename_length = 255 allowed_extensions = ["mp4", "webm", "mkv", "avi", "mov", "m4a", "mp3", "aac", "ogg", "wav", "vtt", "srt"] block_path_traversal = true [download_locations] default = "~/video-downloader"

๐ŸŽฏ Agent Integration Examples

Simple Video Download

User: "Download this YouTube video in good quality" Agent: โ†’ check_ytdlp_support("https://youtube.com/watch?v=dQw4w9WgXcQ") # โœ“ supported โ†’ get_video_formats(url) # finds 720p format โ†’ download_video(url, format_id="22", location_id="default") # downloads to ~/video-downloader/

Quality-Aware Selection

User: "Get the best quality under 100MB" Agent: โ†’ get_video_formats(url) # lists all formats with sizes โ†’ [agent analyzes: 480p=45MB, 720p=95MB, 1080p=180MB] โ†’ download_video(url, format_id="720p") # selects 95MB option

Chained with Web Search

User: "Find and download the latest Corridor Crew video" Agent: โ†’ web_search("Corridor Crew latest video YouTube") # finds URL โ†’ check_ytdlp_support(found_url) # โœ“ supported โ†’ download_video(found_url, location_id="default")

Unsupported Site Analysis

User: "This custom streaming site has a video I need" Agent: โ†’ check_ytdlp_support(url) # โœ— not supported โ†’ analyze_webpage(url) # finds video player type โ†’ extract_media_patterns(url) # extracts manifest URLs โ†’ [returns streaming URLs for manual processing]

โš™๏ธ Configuration

The server creates ~/.config/video-downloader-mcp/config.toml automatically. Customize as needed:

[download_locations] default = "~/video-downloader" movies = "~/Movies/Downloads" music = "~/Music/Downloads" temp = "/tmp/video-downloads" [security] enforce_location_restrictions = true max_filename_length = 255 allowed_extensions = [ "mp4", "webm", "mkv", "avi", "mov", # Video "m4a", "mp3", "aac", "ogg", "wav", # Audio "vtt", "srt", "ass", "ssa" # Subtitles ] [ytdlp] default_format = "best[height<=1080]" default_filename_template = "%(title)s.%(ext)s" [logging] log_security_events = true log_downloads = true

๐Ÿง  LLM Integration Examples

With Claude Code

You: Download this Corridor Crew video in the highest quality available Claude: I'll help you download that video. Let me check what formats are available and download the best quality. [Uses check_ytdlp_support โ†’ get_video_formats โ†’ download_video] โœ… Downloaded: "VFX Artists React to MEGALOPOLIS" (1080p, 250MB) ๐Ÿ“ Location: ~/video-downloader/VFX Artists React to MEGALOPOLIS.mp4

With ChatGPT + MCP

User: Get video information for this educational YouTube video and download the audio-only version ChatGPT: I'll extract the video information and download just the audio for you. [Uses get_video_info โ†’ analyzes metadata โ†’ download_video with audio format] ๐Ÿ“Š Video Info: "Introduction to Machine Learning" (45:32 duration) ๐ŸŽต Downloaded: Audio-only version (m4a, 42MB)

๐Ÿ—๏ธ MCP Architecture Patterns

This server demonstrates several reusable patterns for building secure, agent-friendly MCP servers:

Tool Declaration Pattern

# Reusable pattern for tool definitions types.Tool( name="check_ytdlp_support", description="Check if a URL is supported by yt-dlp and get basic info", inputSchema={ "type": "object", "properties": { "url": {"type": "string", "description": "Video URL to check"} }, "required": ["url"] } )

Security Validation Pattern

# Multi-layer security validation def validate_and_construct_path(self, location_id: str, relative_path: str): # 1. Validate location exists in config # 2. Check path traversal attempts # 3. Canonicalize and verify boundaries # 4. Sanitize filename templates return validated_path

Structured Response Pattern

# Consistent success/error responses try: result = perform_operation() return [types.TextContent( type="text", text=json.dumps({"success": True, "data": result}) )] except Exception as e: return [types.TextContent( type="text", text=json.dumps({"success": False, "error": str(e)}) )]

Configuration Management Pattern

# TOML-based secure configuration class SecureConfigManager: def __init__(self): self.config_path = Path.home() / ".config" / "app-name" / "config.toml" self.load_or_create_default() def get(self, key_path: str, default=None): # Safe nested key access with defaults

Testing

# Run security tests python test_security.py # Test MCP tool functionality python test_mcp_security.py # Run comprehensive workflow tests python test_final_comprehensive.py

๐Ÿค Contributing

We welcome contributions! Please see our contributing guidelines for details.

Development Setup

git clone https://github.com/your-username/video-downloader-mcp.git cd video-downloader-mcp # Install development dependencies pip install -r requirements-dev.txt # Run tests python -m pytest tests/ # Format code black . isort .

๐Ÿ“‹ Requirements

  • Python 3.8+

  • yt-dlp (latest version recommended)

  • MCP library (pip install mcp)

  • Additional dependencies: requests, aiohttp, tomli (Python < 3.11)

๐Ÿ” Troubleshooting

Common Issues

MCP server not loading:

# Check MCP configuration # Ensure full absolute path to server.py # Verify Python environment has required packages

Downloads failing:

# Check yt-dlp installation yt-dlp --version # Verify download directory permissions ls -la ~/video-downloader # Check configuration cat ~/.config/video-downloader-mcp/config.toml

Security validation errors:

# Check that paths don't contain ../ # Verify location_id exists in configuration # Ensure file extensions are in allowed list

Debug Mode

# Enable verbose logging export MCP_DEBUG=1 export YTDLP_DEBUG=1 python server.py

๐Ÿ“ License

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

๐Ÿ™ Acknowledgments

๐Ÿš€ Related Projects

Give your agents video downloading capabilities across 1000+ platforms. ๐ŸŽฌ

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

A Model Context Protocol server that transforms video downloading into a tool-based system for LLM orchestration, allowing users to download videos from 1000+ platforms with intelligent workflows and security features.

  1. ๐ŸŒŸ Features
    1. ๐Ÿš€ Quick Start
      1. Installation
      2. Configuration
      3. First Download
    2. ๐Ÿ› ๏ธ Available Tools
      1. ๐Ÿ”’ Security Features
        1. Built-in Protection
        2. Secure Download Example
        3. Default Security Configuration
      2. ๐ŸŽฏ Agent Integration Examples
        1. Simple Video Download
        2. Quality-Aware Selection
        3. Chained with Web Search
        4. Unsupported Site Analysis
      3. โš™๏ธ Configuration
        1. ๐Ÿง  LLM Integration Examples
          1. With Claude Code
          2. With ChatGPT + MCP
        2. ๐Ÿ—๏ธ MCP Architecture Patterns
          1. Tool Declaration Pattern
          2. Security Validation Pattern
          3. Structured Response Pattern
          4. Configuration Management Pattern
          5. Testing
        3. ๐Ÿค Contributing
          1. Development Setup
        4. ๐Ÿ“‹ Requirements
          1. ๐Ÿ” Troubleshooting
            1. Common Issues
            2. Debug Mode
          2. ๐Ÿ“ License
            1. ๐Ÿ™ Acknowledgments
              1. ๐Ÿš€ Related Projects

                Related MCP Servers

                • MCP Web Tools Server

                  surya-madhav
                  -
                  security
                  A
                  license
                  -
                  quality
                  A Model Context Protocol server that allows LLMs to interact with web content through standardized tools, currently supporting web scraping functionality.
                  Last updated -
                  1
                  MIT License
                  • Linux
                  • Apple

                • YARR Media Stack MCP Server

                  jmagar
                  -
                  security
                  F
                  license
                  -
                  quality
                  A comprehensive Model Context Protocol server that bridges LLMs with self-hosted media services, enabling natural language control of TV shows, movies, downloads, and notifications while maintaining traditional API access.
                  Last updated -

                • MCP URL Fetcher

                  nathanonn
                  A
                  security
                  F
                  license
                  A
                  quality
                  A Model Context Protocol server that enables LLMs to fetch and process web content in multiple formats (HTML, JSON, Markdown, text) with automatic format detection.
                  Last updated -
                  5
                  4
                  • Apple

                • Fetch-Save MCP Server

                  gregberns
                  A
                  security
                  A
                  license
                  A
                  quality
                  A Model Context Protocol server that enables LLMs to retrieve web content and save it to local files for permanent storage and later access.
                  Last updated -
                  1
                  1
                  MIT License

                View all related MCP servers

                Appeared in Searches

                New MCP Servers

                MCP directory API

                We provide all the information about MCP servers via our MCP API.

                curl -X GET 'https://glama.ai/api/mcp/v1/servers/chazmaniandinkle/video-downloader-mcp'

                If you have feedback or need assistance with the MCP directory API, please join our Discord server