YouTube Toolbox

Instructions

Implementation Reference

• server.py:1249-1293 (handler)

  MCP tool handler for get_trending_videos. This is the entry point decorated with @mcp.tool(). It receives parameters, calls the underlying YouTubeService.get_trending_videos helper, formats the response by extracting relevant fields from the API response, and returns structured data including video details, stats, and URLs.
  @mcp.tool( name="get_trending_videos", description="Get trending videos on YouTube by region", ) async def get_trending_videos(region_code: str = None, max_results: int = 5) -> Dict[str, Any]: """ Get trending videos on YouTube by region Args: region_code (str): ISO country code (default: 'US') max_results (int): Maximum number of videos to return (default: 10) Returns: Dict[str, Any]: Trending videos data """ try: # 이제 region_code 처리는 YouTubeService 클래스 내부에서 처리합니다 trending_data = youtube_service.get_trending_videos(region_code, max_results) # Format the response formatted_videos = [] for video in trending_data.get('items', []): formatted_videos.append({ 'id': video.get('id'), 'title': video.get('snippet', {}).get('title'), 'description': video.get('snippet', {}).get('description'), 'publishedAt': video.get('snippet', {}).get('publishedAt'), 'channelId': video.get('snippet', {}).get('channelId'), 'channelTitle': video.get('snippet', {}).get('channelTitle'), 'viewCount': video.get('statistics', {}).get('viewCount'), 'likeCount': video.get('statistics', {}).get('likeCount'), 'commentCount': video.get('statistics', {}).get('commentCount'), 'thumbnails': video.get('snippet', {}).get('thumbnails'), 'url': f"https://www.youtube.com/watch?v={video.get('id')}" }) return { 'videos': formatted_videos, 'region': region_code, 'totalResults': len(formatted_videos) } except Exception as e: logger.exception(f"Error in get_trending_videos: {e}") return {'error': str(e)}
• server.py:388-408 (helper)

  Core helper method in YouTubeService class that performs the actual YouTube Data API v3 call to fetch trending videos using videos.list with chart='mostPopular'. Handles region_code normalization and returns raw API response.
  def get_trending_videos(self, region_code: Optional[str] = 'ko', max_results: Optional[int] = 5) -> Dict[str, Any]: """ Get trending videos for a specific region """ try: params = { 'part': 'snippet,contentDetails,statistics', 'chart': 'mostPopular', 'maxResults': max_results } if region_code: # Normalize region code to ensure valid ISO country code format normalized_code = self.normalize_region_code(region_code) params['regionCode'] = normalized_code response = self.youtube.videos().list(**params).execute() return response except HttpError as e: logger.error(f"Error getting trending videos: {e}") raise e
• server.py:207-227 (helper)

  Helper utility method used by get_trending_videos to normalize region codes (e.g., 'KO' to 'KR') before passing to YouTube API.
  def normalize_region_code(self, region_code: str) -> str: """ Convert region codes to valid ISO 3166-1 alpha-2 country codes """ if not region_code: return None # Common mappings for non-standard codes to standard ISO codes region_mapping = { 'KO': 'KR', # Korea 'EN': 'US', # English -> US as fallback 'JP': 'JP', # Japan 'CN': 'CN', # China } # Convert to uppercase region_code = region_code.upper() # Return mapped code or original if no mapping exists return region_mapping.get(region_code, region_code)
• server.py:672-691 (registration)

  Resource that lists all available tools, including 'get_trending_videos', providing its name and description.
  @mcp.resource( uri='youtube://available-youtube-tools', name="available-youtube-tools", description="Returns a list of YouTube tools available on this MCP server." ) async def get_available_youtube_tools() -> List[Dict[str, str]]: """Returns a list of YouTube tools available on this MCP server.""" available_tools = [ {"name": "search_videos", "description": "Search for YouTube videos with advanced filtering options"}, {"name": "get_video_details", "description": "Get detailed information about a YouTube video"}, {"name": "get_channel_details", "description": "Get detailed information about a YouTube channel"}, {"name": "get_video_comments", "description": "Get comments for a YouTube video"}, {"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."} ] logger.info(f"Resource 'get_available_youtube_tools' called. Returning {len(available_tools)} tools.") return available_tools