search_videos
Find YouTube videos using specific queries with filters for channel, date, duration, quality, captions, and region to locate relevant content.
Instructions
Search for YouTube videos with advanced filtering options
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| max_results | No | ||
| channel_id | No | ||
| order | No | ||
| video_duration | No | ||
| published_after | No | ||
| published_before | No | ||
| video_caption | No | ||
| video_definition | No | ||
| region_code | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
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]: