YouTube Transcript MCP Server

Instructions

Implementation Reference

• src/mcp_youtube_transcript/__init__.py:182-208 (handler)

  Main handler function for 'get_timed_transcript' tool. Parses video URL, fetches transcript snippets using helper, applies pagination and response limit if set, returns TimedTranscript with title, snippets, and next_cursor.

  @mcp.tool()
  async def get_timed_transcript(
      ctx: Context[ServerSession, AppContext],
      url: str = Field(description="The URL of the YouTube video"),
      lang: str = Field(description="The preferred language for the transcript", default="en"),
      next_cursor: str | None = Field(description="Cursor to retrieve the next page of the transcript", default=None),
  ) -> TimedTranscript:
      """Retrieves the transcript of a YouTube video with timestamps."""
  
      title, snippets = _get_transcript_snippets(ctx.request_context.lifespan_context, _parse_video_id(url), lang)
  
      if response_limit is None or response_limit <= 0:
          return TimedTranscript(
              title=title, snippets=[TranscriptSnippet.from_fetched_transcript_snippet(s) for s in snippets]
          )
  
      res = []
      size = len(title) + 1
      cursor = None
      for i, s in islice(enumerate(snippets), int(next_cursor or 0), None):
          snippet = TranscriptSnippet.from_fetched_transcript_snippet(s)
          if size + len(snippet) + 1 > response_limit:
              cursor = str(i)
              break
          res.append(snippet)
  
      return TimedTranscript(title=title, snippets=res, next_cursor=cursor)

• src/mcp_youtube_transcript/__init__.py:72-78 (schema)

  Pydantic model defining the output schema for get_timed_transcript: title, list of timed snippets, and pagination cursor.

  class TimedTranscript(BaseModel):
      """Transcript of a YouTube video with timestamps."""
  
      title: str = Field(description="Title of the video")
      snippets: list[TranscriptSnippet] = Field(description="Transcript snippets of the video")
      next_cursor: str | None = Field(description="Cursor to retrieve the next page of the transcript", default=None)

• src/mcp_youtube_transcript/__init__.py:55-70 (schema)

  Pydantic model for individual timed transcript snippet, used in TimedTranscript.snippets. Includes conversion from youtube_transcript_api snippet.

  class TranscriptSnippet(BaseModel):
      """Transcript snippet of a YouTube video."""
  
      text: str = Field(description="Text of the transcript snippet")
      start: float = Field(description="The timestamp at which this transcript snippet appears on screen in seconds.")
      duration: float = Field(description="The duration of how long the snippet in seconds.")
  
      def __len__(self) -> int:
          return len(self.model_dump_json())
  
      @classmethod
      def from_fetched_transcript_snippet(
          cls: type[TranscriptSnippet], snippet: FetchedTranscriptSnippet
      ) -> TranscriptSnippet:
          return cls(text=snippet.text, start=snippet.start, duration=snippet.duration)

• src/mcp_youtube_transcript/__init__.py:108-125 (helper)

  Cached helper to fetch transcript snippets using YouTubeTranscriptApi, prefers given language or fallback to English. Also scrapes video title from YouTube page.

  @lru_cache
  def _get_transcript_snippets(ctx: AppContext, video_id: str, lang: str) -> Tuple[str, list[FetchedTranscriptSnippet]]:
      if lang == "en":
          languages = ["en"]
      else:
          languages = [lang, "en"]
  
      page = ctx.http_client.get(
          f"https://www.youtube.com/watch?v={video_id}", headers={"Accept-Language": ",".join(languages)}
      )
      page.raise_for_status()
      soup = BeautifulSoup(page.text, "html.parser")
      title = soup.title.string if soup.title and soup.title.string else "Transcript"
  
      transcripts = ctx.ytt_api.fetch(video_id, languages=languages)
      return title, transcripts.snippets

• src/mcp_youtube_transcript/__init__.py:98-106 (helper)

  Helper function to extract YouTube video ID from various URL formats (youtu.be or watch?v=).

  def _parse_video_id(url: str) -> str:
      parsed_url = urlparse(url)
      if parsed_url.hostname == "youtu.be":
          return parsed_url.path.lstrip("/")
      else:
          q = parse_qs(parsed_url.query).get("v")
          if q is None:
              raise ValueError(f"couldn't find a video ID from the provided URL: {url}.")
          return q[0]