YouTube Toolbox

Instructions

Implementation Reference

• server.py:893-965 (handler)

  MCP tool handler for 'search_videos'. Includes registration (@mcp.tool decorator), input schema (function parameters with type hints), and execution logic. Calls the helper method youtube_service.search_videos, formats the API response into a user-friendly structure with video details and URLs, handles errors.
  @mcp.tool( name="search_videos", description="Search for YouTube videos with advanced filtering options", ) async def search_videos( query: str, max_results: Optional[int] = 10, channel_id: Optional[str] = None, order: Optional[str] = None, video_duration: Optional[str] = None, published_after: Optional[str] = None, published_before: Optional[str] = None, video_caption: Optional[str] = None, video_definition: Optional[str] = None, region_code: Optional[str] = None ) -> Dict[str, Any]: """ Search for YouTube videos with advanced filtering options Args: query (str): Search term max_results (int): Number of results to return (1-50) channel_id (str, optional): Filter by specific channel order (str, optional): Sort by date, rating, viewCount, relevance, title video_duration (str, optional): Filter by length (short: <4min, medium: 4-20min, long: >20min) published_after (str, optional): Filter by publish date after (ISO format) published_before (str, optional): Filter by publish date before (ISO format) video_caption (str, optional): Filter by caption availability video_definition (str, optional): Filter by quality (standard/high) region_code (str, optional): Filter by country (ISO country code) Returns: Dict[str, Any]: Search results """ try: options = { 'channelId': channel_id, 'order': order, 'videoDuration': video_duration, 'publishedAfter': published_after, 'publishedBefore': published_before, 'videoCaption': video_caption, 'videoDefinition': video_definition, 'regionCode': region_code } search_results = youtube_service.search_videos(query, max_results, **options) # Format the response formatted_results = [] for item in search_results.get('items', []): video_id = item.get('id', {}).get('videoId') formatted_results.append({ 'videoId': video_id, 'title': item.get('snippet', {}).get('title'), 'channelId': item.get('snippet', {}).get('channelId'), 'channelTitle': item.get('snippet', {}).get('channelTitle'), 'publishedAt': item.get('snippet', {}).get('publishedAt'), 'description': item.get('snippet', {}).get('description'), 'thumbnails': item.get('snippet', {}).get('thumbnails'), 'url': f"https://www.youtube.com/watch?v={video_id}" }) return { 'items': formatted_results, 'totalResults': search_results.get('pageInfo', {}).get('totalResults', 0), 'nextPageToken': search_results.get('nextPageToken') } except Exception as e: logger.exception(f"Error in search_videos: {e}") return {'error': str(e)}
• server.py:228-251 (helper)

  Core helper method in YouTubeService class that performs the actual YouTube Data API v3 search.list() call. Constructs search parameters from inputs, executes the API request, and returns raw API response. Used by the main tool handler.
  def search_videos(self, query: str, max_results: int = 10, **options) -> Dict[str, Any]: """ Search for YouTube videos based on query and options """ try: search_params = { 'part': 'snippet', 'q': query, 'maxResults': max_results, 'type': options.get('type', 'video') } # Add optional parameters if provided for param in ['channelId', 'order', 'videoDuration', 'publishedAfter', 'publishedBefore', 'videoCaption', 'videoDefinition', 'regionCode']: if param in options and options[param]: search_params[param] = options[param] response = self.youtube.search().list(**search_params).execute() return response except HttpError as e: logger.error(f"Error searching videos: {e}") raise e