youtube-summarize

Instructions

Implementation Reference

• main.py:91-120 (handler)

  The main get_transcript tool implementation that fetches YouTube video transcripts. It takes URL, optional languages list, format (text/json/pretty/webvtt/srt), and preserve_formatting flag. It extracts the video ID, fetches the transcript using YouTubeTranscriptApi, formats it using the specified formatter, and handles errors gracefully.

  @mcp.tool()
  def get_transcript(
      url: str,
      languages: list[str] | None = None,
      format: str = "text",
      preserve_formatting: bool = False,
  ) -> str:
      """Fetch a YouTube video's transcript.
  
      Args:
          url: YouTube video URL or video ID
          languages: Preferred languages in priority order (e.g. ["en", "de"]). Defaults to English.
          format: Output format — one of: text, json, pretty, webvtt, srt
          preserve_formatting: Keep HTML formatting tags in the transcript text
      """
      try:
          video_id = extract_video_id(url)
      except ValueError as e:
          return f"Error: {e}"
  
      langs = languages or ["en"]
      try:
          transcript = api.fetch(
              video_id,
              languages=langs,
              preserve_formatting=preserve_formatting,
          )
          return _format_transcript(transcript, format)
      except Exception as e:
          return _handle_transcript_error(e, video_id, langs)

• main.py:91-97 (schema)

  Schema definition for the get_transcript tool via function signature with type hints. Parameters: url (str), languages (list[str] | None), format (str, default 'text'), preserve_formatting (bool, default False). Returns str.

  @mcp.tool()
  def get_transcript(
      url: str,
      languages: list[str] | None = None,
      format: str = "text",
      preserve_formatting: bool = False,
  ) -> str:

• main.py:37-47 (helper)

  Helper function extract_video_id that parses YouTube video URLs or bare IDs. Uses regex patterns to extract the 11-character video ID from various YouTube URL formats or validates a bare ID string.

  def extract_video_id(url_or_id: str) -> str:
      """Extract a YouTube video ID from a URL or bare ID string."""
      url_or_id = url_or_id.strip()
      if BARE_ID_REGEX.match(url_or_id):
          return url_or_id
      match = VIDEO_ID_REGEX.search(url_or_id)
      if match:
          return match.group(1)
      raise ValueError(
          f"Could not extract a YouTube video ID from: {url_or_id}"
      )

• main.py:50-55 (helper)

  Helper function _format_transcript that formats the fetched transcript using one of the available formatters (JSON, PrettyPrint, Text, WebVTT, SRT). Returns an error message if the format is unknown.

  def _format_transcript(transcript, fmt: str) -> str:
      """Format a FetchedTranscript using the specified formatter."""
      formatter = FORMATTERS.get(fmt)
      if formatter is None:
          return f"Error: Unknown format '{fmt}'. Choose from: {', '.join(FORMATTERS)}"
      return formatter.format_transcript(transcript)

• main.py:58-88 (helper)

  Helper function _handle_transcript_error that converts various youtube_transcript_api exceptions (TranscriptsDisabled, NoTranscriptFound, VideoUnavailable, InvalidVideoId, AgeRestricted, IpBlocked, RequestBlocked) into user-friendly error messages.

  def _handle_transcript_error(e: Exception, video_id: str, languages: list[str] | None = None) -> str:
      """Convert youtube_transcript_api exceptions into user-friendly error strings."""
      from youtube_transcript_api import (
          AgeRestricted,
          InvalidVideoId,
          IpBlocked,
          NoTranscriptFound,
          RequestBlocked,
          TranscriptsDisabled,
          VideoUnavailable,
      )
  
      if isinstance(e, TranscriptsDisabled):
          return f"Error: Transcripts are disabled for video '{video_id}'."
      if isinstance(e, NoTranscriptFound):
          lang_str = ", ".join(languages) if languages else "any"
          return (
              f"Error: No transcript found for video '{video_id}' "
              f"in language(s): {lang_str}. Use list_transcripts to see available languages."
          )
      if isinstance(e, VideoUnavailable):
          return f"Error: Video '{video_id}' is unavailable."
      if isinstance(e, InvalidVideoId):
          return f"Error: '{video_id}' is not a valid YouTube video ID."
      if isinstance(e, AgeRestricted):
          return f"Error: Video '{video_id}' is age-restricted and cannot be accessed."
      if isinstance(e, IpBlocked):
          return "Error: YouTube is blocking requests from this IP address."
      if isinstance(e, RequestBlocked):
          return "Error: The request to YouTube was blocked."
      return f"Error fetching transcript for '{video_id}': {e}"