YouTube MCP

Instructions

Args:
    url: YouTube video URL or video ID

Returns:
    The timestamped transcript text

Implementation Reference

• main.py:74-98 (handler)

  The main handler function for the 'get_youtube_transcript_tool' tool, decorated with @mcp.tool() to register it with the FastMCP server. It processes the YouTube URL, extracts the video ID, fetches the transcript using helpers, formats the output, and returns a user-friendly response.

  @mcp.tool()
  async def get_youtube_transcript_tool(url: str) -> str:
      """Extract English transcript with timestamps from a YouTube video using its URL or video ID.
      
      Args:
          url: YouTube video URL or video ID
      
      Returns:
          The timestamped transcript text
      """
      try:
          video_id = extract_video_id(url)
          result = get_youtube_transcript(video_id)
          
          if result['success']:
              response = f"✅ Successfully extracted English transcript for video: {video_id}\n\n"
              response += f"📄 Transcript with timestamps:\n{result['transcript']}\n\n"
              response += f"🔍 Total segments: {result['segments_count']}"
              
              return response
          else:
              return f"❌ Failed to extract transcript: {result['error']}"
      
      except Exception as e:
          return f"❌ Error processing video: {str(e)}"

• main.py:44-71 (helper)

  Helper function that fetches the English transcript from YouTube using youtube_transcript_api, formats it with timestamps using format_timestamp, and returns a structured dict with success status.

  def get_youtube_transcript(video_id: str) -> dict[str, Any]:
      """Get YouTube transcript using youtube-transcript-api (English only)."""
      try:
          # Get English transcript
          transcript_list = YouTubeTranscriptApi.get_transcript(video_id, ['en'])
          
          # Create timestamped transcript
          timestamped_transcript = []
          for entry in transcript_list:
              timestamp = format_timestamp(entry['start'])
              timestamped_transcript.append(f"[{timestamp}] {entry['text']}")
          
          # Join all segments
          full_transcript = '\n'.join(timestamped_transcript)
          
          return {
              'success': True,
              'video_id': video_id,
              'transcript': full_transcript,
              'segments_count': len(transcript_list)
          }
      
      except Exception as e:
          return {
              'success': False,
              'error': str(e),
              'video_id': video_id
          }

• main.py:12-29 (helper)

  Helper function to extract the YouTube video ID from various URL formats using regular expressions.

  def extract_video_id(url: str) -> str:
      """Extract YouTube video ID from various YouTube URL formats."""
      # Handle different YouTube URL formats
      patterns = [
          r'(?:youtube\.com/watch\?v=|youtu\.be/|youtube\.com/embed/)([a-zA-Z0-9_-]{11})',
          r'youtube\.com/watch\?.*v=([a-zA-Z0-9_-]{11})',
      ]
      
      for pattern in patterns:
          match = re.search(pattern, url)
          if match:
              return match.group(1)
      
      # If no pattern matches, maybe it's already a video ID
      if len(url) == 11 and re.match(r'^[a-zA-Z0-9_-]{11}$', url):
          return url
      
      raise ValueError(f"Could not extract video ID from URL: {url}")

• main.py:32-41 (helper)

  Helper function to format seconds into a readable timestamp string (MM:SS or HH:MM:SS).

  def format_timestamp(seconds: float) -> str:
      """Convert seconds to MM:SS or HH:MM:SS format."""
      hours = int(seconds // 3600)
      minutes = int((seconds % 3600) // 60)
      seconds = int(seconds % 60)
      
      if hours > 0:
          return f"{hours:02d}:{minutes:02d}:{seconds:02d}"
      else:
          return f"{minutes:02d}:{seconds:02d}"