YouTube Toolbox

Instructions

Implementation Reference

• server.py:893-965 (handler)

  MCP tool handler function for search_videos. Registers the tool with @mcp.tool decorator, defines input schema via parameters, handles arguments, calls helper method, formats response.
  @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 constructs YouTube API search parameters and executes the search.list API call.
  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
• server.py:679-691 (registration)

  The tool is listed in the available-youtube-tools resource, which provides a list of all available tools including search_videos.
  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
• server.py:898-908 (schema)

  Input schema defined by the function parameters with type hints and defaults, used by MCP for tool calling.
  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]: