YouTube Search & Download MCP Server

Instructions

Implementation Reference

• src/youtube_search_mcp/tools/download_tools.py:35-80 (handler)

  The tool handler that receives the MCP tool request, validates input, and orchestrates the download.

  async def download_video(
      video_id: str,
      quality: str = "best",
      output_dir: str | None = None,
      format: str = "mp4",
  ) -> str:
      """
      Download a YouTube video with configurable quality.
  
      Args:
          video_id: YouTube video ID (11 characters)
          quality: Quality preset - "best", "high" (1080p), "medium" (720p), "low" (480p)
          output_dir: Download directory path (uses config default if not specified)
          format: Output format - "mp4", "webm", "mkv" (default: "mp4")
  
      Returns:
          JSON with download status, file path, file size, and metadata
  
      Example:
          download_video("dQw4w9WgXcQ", quality="high", format="mp4")
      """
      try:
          logger.info(
              f"Download video request: video_id='{video_id}', quality='{quality}', format='{format}'"
          )
  
          # Validate video ID
          if not validate_video_id(video_id):
              raise InvalidQueryError(f"Invalid video ID format: {video_id}")
  
          # Create download parameters
          params = DownloadParams(
              video_id=video_id,
              quality=quality,
              output_dir=output_dir,
              format=format,
              download_type="video",
          )
  
          # Execute download
          downloader = get_downloader()
          result = await downloader.download_video(params)
  
          logger.info(f"Video download completed: {result.file_path}")
          return json.dumps(result.model_dump(), indent=2)

• src/youtube_search_mcp/download/ytdlp_downloader.py:60-80 (handler)

  The actual implementation of the video download logic using yt-dlp.

  async def download_video(self, params: DownloadParams) -> DownloadResult:
      """
      Download a video with specified quality and format.
  
      Args:
          params: Download parameters
  
      Returns:
          Download result with file path and metadata
  
      Raises:
          VideoNotFoundError: If video doesn't exist
          DownloadError: If download operation fails
          DiskSpaceError: If insufficient disk space
          PermissionError: If cannot write to output directory
      """
      logger.info(
          f"Starting video download: {params.video_id} "
          f"(quality={params.quality}, format={params.format})"
      )
      return await self._download(params, is_video=True)