Yt Dlp MCP Container

yt-dlp MCP 容器

一个容器化的yt-dlp服务器，具备远程SSE基于的MCP集成以供Claude AI使用，并提供REST API用于工件管理

概述

为何这很重要

• 克劳德集成（或译为“克劳德整合”）克劳德可以通过自然对话直接下载并分析视频
• 远程访问基于SSE的MCP终端使Claude能够从任何地方通过HTTPS进行连接
• 双接口使用通过Claude或REST API的MCP工具进行直接访问
• 准备就绪，可投入生产已容器化并针对Zeabur平台进行了优化部署

主要特点

1. 远程SSE MCP终端

• 将 yt-dlp 的功能作为 MCP 工具提供，可通过 服务器发送事件
• 克劳德进行远程连接 https://your-app.zeabur.app/sse
• 通过持久HTTP连接实现的实时双向通信
• 无需本地安装

2. FastMCP与FastAPI的集成

• FastMCP 将 yt-dlp CLI 封装为类型安全的 MCP 工具
• MCP服务器作为SSE端点安装在FastAPI中
• 支持非阻塞下载的异步/等待（Async/await）功能
• 干净、可维护的Python代码库

3. 艺术品管理REST API

• 状态检查监控下载进度和完成情况
• 工件下载检索已处理的视频/音频文件
• 资源管理清理旧的下载文件
• 健康监测服务健康检查

4. 广泛的平台支持

由 yt-dlp 提供支持，支持从以下来源下载：

• YouTube，YouTube Music（优兔音乐）
• Vimeo，Dailymotion（这两个都是视频分享网站）
• Twitter/X、Facebook、Instagram
• Twitch，TikTok
• 1000多个更多平台

建筑学

┌─────────────┐         SSE (HTTPS)         ┌──────────────────┐
│             │────────────────────────────▶ │   FastAPI App    │
│   Claude    │                              │                  │
│             │◀────────────────────────────│  SSE Endpoint    │
└─────────────┘      MCP Protocol           │    (/sse)        │
                                             │                  │
                                             │   ┌──────────┐   │
                                             │   │ FastMCP  │   │
                                             │   │  Server  │   │
                                             │   └────┬─────┘   │
┌─────────────┐         REST API            │        │         │
│   User/     │────────────────────────────▶│        ▼         │
│   Browser   │                              │   yt-dlp CLI    │
│             │◀────────────────────────────│                  │
└─────────────┘    Status/Artifacts         └────────┬─────────┘
                                                      │
                                                      ▼
                                             ┌─────────────────┐
                                             │  File Storage   │
                                             │  (Downloads)    │
                                             └─────────────────┘

它是如何运作的

1. 克劳德连接克劳德作为远程MCP服务器连接到SSE终端
2. 工具调用克劳德称之为MCP工具（例如。， download_video)
3. 处理FastMCP 将呼叫路由到 yt-dlp 命令行界面，执行下载操作
4. 存储下载的文件存储在指定目录中，每个文件都有唯一标识符
5. 状态与检索通过REST API监控进度，准备好后下载工件

快速入门

第一步：安装

选择您的部署方法：

• 本地开发： 本地安装指南
• 云部署： Zeabur 安装指南

两种选项都需要通过Cookie认证才能访问YouTube。请参阅 Cookie 认证指南 用于设置说明。

步骤2：配置Claude

添加到您的Claude桌面配置中：

macOS（苹果电脑操作系统）： ~/Library/Application Support/Claude/claude_desktop_config.json Windows： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "yt-dlp": {
      "type": "http",
      "url": "http://localhost:8000/mcp/"
    }
  }
}

对于Zeabur部署，请替换为您的应用URL： https://your-app.zeabur.app/mcp/

重启Claude桌面版 并且 yt-dlp 工具将可用！

步骤3：开始使用

开启一段新对话并尝试：

Download video from https://www.youtube.com/watch?v=dQw4w9WgXcQ

如需完整的设置说明，请参阅 安装指南.md

MCP 工具

连接后，克劳德可以访问这些工具：

要查看所有工具的详细文档、参数、示例和使用说明，请参阅 MCP工具使用说明.md

REST API

FastAPI 服务器还提供了 REST 端点以供直接访问：

GET /health

健康检查端点。

回复：

{
  "status": "healthy",
  "service": "yt-dlp-mcp",
  "version": "1.0.0"
}

GET /downloads

列出所有下载及其状态。

回答：

{
  "downloads": [
    {
      "id": "7a8f9e2b",
      "url": "https://youtube.com/watch?v=...",
      "status": "completed",
      "filename": "video.mp4",
      "size": 15728640,
      "created_at": "2025-01-13T10:30:00Z",
      "completed_at": "2025-01-13T10:32:15Z"
    }
  ]
}

GET /downloads/{download_id}

获取特定下载的状态。

回答：

{
  "id": "7a8f9e2b",
  "status": "in_progress",
  "progress": 45.2,
  "eta": "00:01:30",
  "speed": "2.5MB/s"
}

状态值：

• pending已排队，尚未开始
• in_progress正在下载中
• completed准备下载
• failed发生了错误

GET /artifacts/{download_id}

下载处理后的视频/音频文件。

回答： 带有适当Content-Type头部的二进制文件流

示例：

curl -O https://your-app.zeabur.app/artifacts/7a8f9e2b

DELETE /downloads/{download_id}

删除一个下载项及其相关文件。

回答：

{
  "message": "Download and artifacts deleted successfully",
  "id": "7a8f9e2b"
}

配置

使用环境变量配置服务：

| 不 | 注：

现在，启动时会自动使用无头模式的Chromium生成Cookies。无需手动导出Cookies！ 有关详细配置和设置说明，请参阅

INSTALLATION_GUIDE.md 翻译为中文是：安装指南.md

使用示例

1. 典型工作流程 用户要求克劳德下载 download_video() → 克劳德使用
2. MCP工具 获取下载ID
3. → 用于追踪和检索 监控进度 get_download_status() → 使用
4. MCP工具或REST API 下载工件（或：下载制品） /artifacts/{download_id}

使用REST API终端点

• 这种混合方法结合了： MCP工具
• 用于AI驱动的交互与自动化 REST API（Representational State Transfer Application Programming Interface，表述性状态传递应用程序编程接口）

用于直接文件访问和与其他工具的集成 如需查看包含真实工作流程的完整示例，请参阅

MCP工具使用指南.md

发展

本地设置

git clone https://github.com/yourusername/yt-dlp-mcp-container.git
cd yt-dlp-mcp-container
cp .env.example .env     # Copy environment template
docker-compose up -d     # Start server with auto-generated cookies

快速入门： 如需详细的设置说明，请参阅

安装指南.md

yt-dlp-mcp-container/
├── server.py              # FastAPI + FastMCP application
├── download_manager.py    # Download queue and status tracking
├── cookie_generator.py    # Headless Chromium cookie generator
├── entrypoint.sh          # Container startup script
├── requirements.txt       # Python dependencies
├── Dockerfile             # Container configuration
├── docker-compose.yml     # Local development setup
├── .env.example           # Environment template
├── README.md              # This file
├── INSTALLATION_GUIDE.md  # Complete installation guide
├── MCP_TOOLS_USAGE.md     # Tool documentation
└── downloads/             # Storage directory (created at runtime)

项目结构

贡献；助力

1. 欢迎投稿！请：
2. 为仓库创建分支副本git checkout -b feature/amazing-feature创建一个特性分支（
3. )git commit -m 'Add amazing feature'提交您的更改（
4. ）git push origin feature/amazing-feature推送到分支（
5. )

提交一个拉取请求

法律免责声明 ⚠️（警告或注意的符号，无具体文字含义）重要的

• 此工具仅供教育和个人使用。
• 只下载你有权下载的视频
• 遵守版权法和平台服务条款
• 注意并遵守当地关于内容下载的法律法规

此工具不应被用于侵犯知识产权

作者和贡献者不对该工具的使用方式负责。

故障排除

常见问题

• MCP 工具不可用：
• 配置更改后重启Claude桌面版
• 开始新对话（MCP在对话开始时连接） curl http://localhost:8000/health

验证服务器健康状况：

• YouTube机器人检测：
• 确保cookie已正确配置
• 如果过期，则重新出口新鲜饼干（注：此句在实际商业语境中可能略显生硬，更自然的表达可能是“如已过期，则提供新鲜饼干作为替换”或“如饼干过期，请更换为新鲜饼干”） 见

Cookie认证指南

• 下载失败：
• 检查日志中的 yt-dlp 错误信息
• 验证视频URL是否有效且可访问

确保有足够的磁盘空间 如需进行全面的故障排除，请参阅

INSTALLATION_GUIDE.md 翻译为中文是：安装指南.md

许可证 这个项目遵循MIT许可证授权——详见 许可证

文件中有详细信息。

版权所有 (c) 2025 Ho Ming-Cheng

致谢与鸣谢

• 这个项目是基于优秀的开源工具构建的： yt-dlp（可直接译为“YouTube下载器”或根据具体语境译为“视频下载工具”等）
• - 强大的视频下载器 FastMCP
• - 用于构建MCP服务器的Python框架 FastAPI
• - 用于构建API的现代网络框架 模型上下文协议
• - 人工智能工具集成协议 克劳德

- 人类中心主义公司的AI助手

• 支持问题 ：
• GitHub Issues（在GitHub上报告的问题）讨论 :
• GitHub 讨论区文档 :

______________________________________________________________________

维基

为Claude和MCP社区用心打造