使用说明

项目简介

'Media Downloader' 是一个功能强大的工具，能够从 YouTube、Twitter、Rumble 等多个主流平台下载视频和音频。它不仅提供了命令行和Python库接口供开发者和用户直接使用，更重要的是，它作为一个符合 Model Context Protocol (MCP) 标准的服务器实现，能够将媒体下载能力封装为可供大型语言模型（LLM）客户端调用的“工具”。通过这种方式，LLM可以与该服务器交互，实现AI驱动的自动化媒体下载、管理和处理。该服务器支持多种传输协议，能够处理JSON-RPC请求，提供下载进度报告，并将下载文件的最终路径返回给调用方。

主要功能点

多平台媒体下载: 支持从 YouTube、Twitter、Rumble、BitChute、Vimeo 等主流视频平台下载内容。
音频/视频选择: 客户端可以选择仅下载音频（MP3格式）或下载完整的视频文件。
自定义保存路径: 允许在下载时指定媒体文件的保存目录。
LLM工具集成: 作为MCP服务器，它将媒体下载的核心能力封装为名为 'download_media' 的工具，供大型语言模型（LLM）客户端进行调用，实现AI赋能的自动化下载流程。
下载进度报告: 服务器在执行下载任务时，能够向LLM客户端实时报告下载进度。
多种传输协议: 支持通过 Stdio, HTTP 或 SSE 等多种传输协议与MCP客户端进行通信。

安装步骤

在本地机器上运行 'Media Downloader' MCP 服务器需要安装相应的Python包。

安装Python: 确保您的系统已安装 Python 3.8 或更高版本。

安装'media-downloader'库: 打开终端或命令提示符，运行以下命令来安装核心库：

python -m pip install media-downloader

（可选）使用Docker部署: 如果您希望通过Docker容器化部署MCP服务器，可以使用官方提供的镜像：

docker pull knucklessg1/media-downloader:latest

服务器配置

MCP客户端需要一份JSON格式的配置信息，以便发现并连接到 'Media Downloader' MCP 服务器。以下是MCP客户端中 'mcp.json' 文件的配置示例，用于定义如何启动并与此服务器交互：

{
  "mcpServers": {
    "media_downloader": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "media-downloader",
        "media-downloader-mcp",
        "--transport=http",
        "--host=0.0.0.0",
        "--port=8000"
      ],
      "env": {
        "DOWNLOAD_DIRECTORY": "~/Downloads", // (可选) 设置下载文件的默认目录，LLM可在调用时覆盖此值
        "AUDIO_ONLY": "false" // (可选) 设置是否默认只下载音频，LLM可在调用时覆盖此值
      },
      "timeout": 300000 // 服务器响应超时时间（毫秒），根据需要调整
    }
  }
}

配置说明：

'"media_downloader"': 这是您给该MCP服务器实例定义的名称。
'"command"': 指定用于启动MCP服务器进程的命令。在此示例中，使用 'uv' 工具。
'"args"': 传递给 'command' 的参数列表。
- '"run", "--with", "media-downloader", "media-downloader-mcp"': 这是 'uv' 运行 'media-downloader' 包中 'media_downloader_mcp' 模块的指令，该模块是MCP服务器的入口点。
- '"--transport=http"': 指定服务器使用的传输协议为HTTP。您也可以选择 'stdio' 或 'sse'。
- '"--host=0.0.0.0"': 服务器监听的IP地址。
- '"--port=8000"': 服务器监听的端口号。
'"env"': (可选) 用于设置MCP服务器进程的环境变量。
- '"DOWNLOAD_DIRECTORY"': 默认的下载目录。
- '"AUDIO_ONLY"': 默认是否只下载音频。
'"timeout"': LLM客户端等待服务器响应的最大时间。

基本使用方法

'Media Downloader' MCP 服务器主要为MCP客户端（通常是大型语言模型应用）提供服务，而非直接由最终用户操作。

部署MCP服务器: 根据您的选择，通过Python或Docker启动MCP服务器。

Python: 如果在本地直接运行，可以在终端中执行：

python -m media_downloader --transport=http --host=0.0.0.0 --port=8000

Docker Compose: 使用上述Docker镜像和 'compose.yml' 示例文件（请确保 'downloads' 卷正确映射到宿主机路径）：

services:
  media-downloader-mcp:
    image: knucklessg1/media-downloader:latest
    volumes:
      - ./my_downloads:/root/Downloads # 将宿主机的 my_downloads 目录映射到容器内的 /root/Downloads
    environment:
      - HOST=0.0.0.0
      - PORT=8000
    ports:
      - 8000:8000

保存为 'compose.yml' 后，运行：

docker compose up -d

MCP客户端调用（LLM交互）: 一旦MCP服务器启动并运行，支持MCP协议的LLM客户端就可以根据上述 'mcp.json' 配置连接到它。当LLM需要执行下载任务时，它会向该MCP服务器发送一个JSON-RPC请求，调用 'download_media' 工具，并传递所需参数。

LLM提示词示例:

Download me this video: https://youtube.com/watch?v=askdjfa and save it to my "C:\Users\User\Videos" folder.

LLM客户端发送的JSON-RPC请求示例 (由LLM客户端根据提示词生成):

{
  "jsonrpc": "2.0",
  "method": "tool_code/download_media",
  "params": {
    "video_url": "https://youtube.com/watch?v=askdjfa",
    "download_directory": "C:\\Users\\User\\Videos",
    "audio_only": false
  },
  "id": 1
}

MCP服务器响应示例: 服务器执行下载任务后，会将下载文件的完整路径作为结果返回给LLM客户端：

{
  "jsonrpc": "2.0",
  "result": "C:\\Users\\User\\Videos\\YouTube Video - Episode 1.mp4",
  "id": 1
}

在下载过程中，服务器还会通过 MCP Context 向客户端发送进度报告通知。

关键词