YouTube Toolbox

Instructions

Implementation Reference

• server.py:1132-1205 (handler)

  Primary MCP tool handler implementing the get_video_transcript tool. Fetches video metadata using YouTube API, retrieves transcript segments via helper, formats with timestamps, and returns structured data including metadata, segment list, and plain timestamped text.

  @mcp.tool(
      name="get_video_transcript",
      description="Get transcript/captions for a YouTube video",
  )
  async def get_video_transcript(video_id: str, language: Optional[str] = 'ko') -> Dict[str, Any]:
      """
      Get transcript/captions for a YouTube video
      
      Args:
          video_id (str): YouTube video ID
          language (str, optional): Language code (e.g., 'en', 'ko', 'fr')
      
      Returns:
          Dict[str, Any]: Transcript data
      """
      try:
          # Get video details for metadata
          video_data = youtube_service.get_video_details(video_id)
          
          if not video_data.get('items'):
              return {'error': f"Video with ID {video_id} not found"}
              
          video = video_data['items'][0]
          
          # Get transcript
          try:
              transcript_data = youtube_service.get_video_transcript(video_id, language)
              
              # Format transcript with timestamps
              formatted_transcript = []
              for segment in transcript_data:
                  text = getattr(segment, 'text', '')
                  start = getattr(segment, 'start', 0)
                  duration = getattr(segment, 'duration', 0)
                  
                  formatted_transcript.append({
                      'text': text,
                      'start': start,
                      'duration': duration,
                      'timestamp': youtube_service.format_time(int(start * 1000))
                  })
              
              # Create metadata
              metadata = {
                  'videoId': video.get('id'),
                  'title': video.get('snippet', {}).get('title'),
                  'channelTitle': video.get('snippet', {}).get('channelTitle'),
                  'language': language or 'default',
                  'segmentCount': len(transcript_data)
              }
              
              # Create timestamped text version
              timestamped_text = "\n".join([
                  f"[{item['timestamp']}] {item['text']}" 
                  for item in formatted_transcript
              ])
              
              return {
                  'metadata': metadata,
                  'transcript': formatted_transcript,
                  'text': timestamped_text,
                  'channelId': video.get('snippet', {}).get('channelId')
              }
          except Exception as e:
              return {
                  'error': f"Could not retrieve transcript: {str(e)}",
                  'videoId': video_id,
                  'title': video.get('snippet', {}).get('title')
              }
              
      except Exception as e:
          logger.exception(f"Error in get_video_transcript: {e}")
          return {'error': str(e)}

• server.py:312-342 (helper)

  Core helper method in YouTubeService that fetches raw transcript segments using youtube_transcript_api. Supports language-specific transcripts with fallbacks to generated and English transcripts.

  def get_video_transcript(self, video_id: str, language: Optional[str] = 'ko') -> List[Dict[str, Any]]:
      """
      Get transcript for a specific YouTube video
      """
      video_id = self.parse_url(video_id)
      
      try:
          if language:
              transcript_list = YouTubeTranscriptApi.list_transcripts(video_id)
              try:
                  transcript = transcript_list.find_transcript([language])
                  return transcript.fetch()
              except NoTranscriptFound:
                  # Fallback to generated transcript if available
                  try:
                      transcript = transcript_list.find_generated_transcript([language])
                      return transcript.fetch()
                  except:
                      # Final fallback to any available transcript
                      transcript = transcript_list.find_transcript(['en'])
                      return transcript.fetch()
          else:
              return YouTubeTranscriptApi.get_video_transcript(video_id)
              
      except (TranscriptsDisabled, NoTranscriptFound) as e:
          logger.error(f"No transcript available for video {video_id}: {e}")
          return []
      except Exception as e:
          logger.error(f"Error getting transcript for video {video_id}: {e}")
          raise e

• server.py:684-687 (registration)

  The tool is listed in the available-youtube-tools resource, confirming its registration and providing description.

  {"name": "get_video_transcript", "description": "Get transcript/captions for a YouTube video"},
  {"name": "get_related_videos", "description": "Get videos related to a specific YouTube video"},
  {"name": "get_trending_videos", "description": "Get trending videos on YouTube by region"},
  {"name": "get_video_enhanced_transcript", "description": "Advanced transcript extraction tool with filtering, search, and multi-video capabilities. Provides rich transcript data for detailed analysis and processing. Features: 1) Extract transcripts from multiple videos; 2) Filter by time ranges; 3) Search within transcripts; 4) Segment transcripts; 5) Format output in different ways; 6) Include video metadata."}