search-videos
Search YouTube videos with advanced filters like channel, duration, publish date, quality, and more. Customize results by relevancy, view count, or date. Retrieve up to 50 videos per search.
Instructions
Search for YouTube videos with advanced filtering options. Supports parameters: - query: Search term (required) - maxResults: Number of results to return (1-50) - channelId: Filter by specific channel - order: Sort by date, rating, viewCount, relevance, title - type: Filter by resource type (video, channel, playlist) - videoDuration: Filter by length (short: <4min, medium: 4-20min, long: >20min) - publishedAfter/publishedBefore: Filter by publish date (ISO format) - videoCaption: Filter by caption availability - videoDefinition: Filter by quality (standard/high) - regionCode: Filter by country (ISO country code)
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| channelId | No | ||
| maxResults | No | ||
| order | No | ||
| publishedAfter | No | ||
| publishedBefore | No | ||
| query | Yes | ||
| regionCode | No | ||
| type | No | ||
| videoCaption | No | ||
| videoDefinition | No | ||
| videoDuration | No |
Implementation Reference
- src/index.ts:207-263 (registration)Full registration of the 'search-videos' MCP tool, including name, description, input schema with Zod validation, and inline handler function that delegates to YouTubeService.searchVideos
server.tool( 'search-videos', 'Search for YouTube videos with advanced filtering options. Supports parameters: \ - query: Search term (required) \ - maxResults: Number of results to return (1-50) \ - channelId: Filter by specific channel \ - order: Sort by date, rating, viewCount, relevance, title \ - type: Filter by resource type (video, channel, playlist) \ - videoDuration: Filter by length (short: <4min, medium: 4-20min, long: >20min) \ - publishedAfter/publishedBefore: Filter by publish date (ISO format) \ - videoCaption: Filter by caption availability \ - videoDefinition: Filter by quality (standard/high) \ - regionCode: Filter by country (ISO country code)', { query: z.string().min(1), maxResults: z.number().min(1).max(50).optional(), channelId: z.string().optional(), order: z.enum(['date', 'rating', 'relevance', 'title', 'videoCount', 'viewCount']).optional(), type: z.enum(['video', 'channel', 'playlist']).optional(), videoDuration: z.enum(['any', 'short', 'medium', 'long']).optional(), publishedAfter: z.string().regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/).optional(), publishedBefore: z.string().regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/).optional(), videoCaption: z.enum(['any', 'closedCaption', 'none']).optional(), videoDefinition: z.enum(['any', 'high', 'standard']).optional(), regionCode: z.string().length(2).optional() }, async ({ query, maxResults = 10, channelId, order, type, videoDuration, publishedAfter, publishedBefore, videoCaption, videoDefinition, regionCode }) => { try { const searchResults = await youtubeService.searchVideos(query, maxResults, { channelId, order, type, videoDuration, publishedAfter, publishedBefore, videoCaption, videoDefinition, regionCode }); return { content: [{ type: 'text', text: JSON.stringify(searchResults, null, 2) }] }; } catch (error) { return { content: [{ type: 'text', text: `Error searching videos: ${error}` }], isError: true }; } } ); - src/youtube-service.ts:31-66 (handler)Core handler implementation in YouTubeService class that performs the actual YouTube API search.list call with all supported filters and options for video search.
async searchVideos( query: string, maxResults: number = 10, options: { channelId?: string; order?: string; type?: string; videoDuration?: string; publishedAfter?: string; publishedBefore?: string; videoCaption?: string; videoDefinition?: string; regionCode?: string; } = {} ): Promise<youtube_v3.Schema$SearchListResponse> { try { const response = await this.youtube.search.list({ part: ['snippet'], q: query, maxResults, type: options.type ? [options.type] : ['video'], channelId: options.channelId, order: options.order, videoDuration: options.videoDuration, publishedAfter: options.publishedAfter, publishedBefore: options.publishedBefore, videoCaption: options.videoCaption, videoDefinition: options.videoDefinition, regionCode: options.regionCode }); return response.data; } catch (error) { console.error('Error searching videos:', error); throw error; } }