YouTube MCP Server

Instructions

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; } }