Video Downloader MCP Server

🎬 视频下载器MCP服务器

  

让您的代理能够从1000多个具有内置安全功能的网站下载视频。 此MCP服务器提供7个独立的工具，代理可以使用这些工具从几乎任何网页检查、分析和下载视频。基于yt-dlp构建，具有安全验证和回退分析功能。

🌟 特性

• 🛠️ 7 MCP工具 -用于检查、分析和下载视频的独立功能
• 🔒 内置安全 -路径验证、位置限制和输入净化
• 🌐 支持1000+个网站 -YouTube、Facebook、TikTok，以及通过yt-dlp访问的数百个其他网站
• 🔄 回退分析 -yt-dlp不支持站点时的模式匹配
• 📁 有组织的下载 -具有文件名模板的可配置安全位置
• ⚙️ 代理商友好 -干净的JSON响应和结构化错误处理

🚀 快速开始

安装

# 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

配置

添加到您的MCP客户端配置中（例如，Claude Desktop）：

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

首次下载

您的客服现在可以通过简单的工具调用下载视频：

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

🛠️ 可用工具

🔒 安全功能

内置保护

• 路径穿越预防 -积木 ../ 目录转义尝试
• 位置限制 -仅下载到配置的安全目录
• 扩展验证 -只允许安全的文件类型（视频/音频/字幕）
• 模板消毒 -删除危险的shell字符
• TOML配置 -无反序列化漏洞

安全下载示例

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

默认安全配置

[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"

🎯 代理集成示例

简单视频下载

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/

质量意识选择

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

与网络搜索链接

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")

不支持的站点分析

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]

⚙️ 配置

服务器创建 ~/.config/video-downloader-mcp/config.toml 自动。根据需要进行自定义：

[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集成示例

使用克劳德代码

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

使用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架构模式

此服务器演示了几种可重用的模式，用于构建安全、对代理友好的MCP服务器：

工具声明模式

# 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"]
    }
)

安全验证模式

# 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

结构化响应模式

# 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)})
    )]

配置管理模式

# 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

测试

# 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

🤝 贡献

我们欢迎捐款！请查看我们的 贡献指南 了解详情。

开发设置

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 .

📋 需求

• Python 3.8+
• yt-dlp （推荐最新版本）
• MCP库 (pip install mcp)
• 附加依赖项: requests, aiohttp, tomli （Python\<3.11）

🔍 故障排除

常见问题

MCP服务器未加载：

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

下载失败：

# Check yt-dlp installation
yt-dlp --version

# Verify download directory permissions  
ls -la ~/video-downloader

# Check configuration
cat ~/.config/video-downloader-mcp/config.toml

安全验证错误：

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

调试模式

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

📝 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

🙏 致谢

• yt-dlp -强大的视频提取引擎使这成为可能
• 模型上下文协议 -实现无缝LLM工具集成
• Anthropic -适用于Claude和MCP规范

🚀 相关项目

• MCP规范 -MCP官方文件
• 克劳德代码 -Claude的代码编辑环境
• yt-dlp -底层视频提取库

______________________________________________________________________

为您的代理提供跨1000多个平台的视频下载功能。 🎬