search_youtube
Search YouTube videos with a query, retrieve results including titles, thumbnails, and links. Supports pagination, sorting, and filtering by date or duration using the SearchAPI MCP Server.
Instructions
Performs a YouTube search using SearchAPI.site. Requires a search query and your SearchAPI.site API key. Returns formatted YouTube search results including video titles, thumbnails, descriptions, and links. Supports optional parameters for pagination, sorting, filtering by date and duration.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| maxResults | No | Maximum number of results to return (1-50) | |
| order | No | Sort order for results | |
| pageToken | No | Token for pagination to get next/previous page of results | |
| publishedAfter | No | Number of days to filter videos from | |
| query | Yes | The YouTube search query to perform | |
| videoDuration | No | Filter by video duration |
Implementation Reference
- src/tools/searchapi.tool.ts:106-145 (handler)MCP tool handler function that executes the search_youtube tool logic by calling the controller and formatting the response for MCP.async function handleYouTubeSearch(args: YouTubeSearchToolArgsType) { const methodLogger = Logger.forContext( 'tools/searchapi.tool.ts', 'handleYouTubeSearch', ); methodLogger.debug(`Performing YouTube search for query: ${args.query}`); try { // Map tool arguments to controller options const controllerOptions = { query: args.query, maxResults: args.maxResults, pageToken: args.pageToken, order: args.order, publishedAfter: args.publishedAfter, videoDuration: args.videoDuration, }; // Call the controller with the mapped options const result = await searchApiController.youtubeSearch(controllerOptions); methodLogger.debug(`Got the response from the controller`, result); // Format the response for the MCP tool return { content: [ { type: 'text' as const, text: result.content, }, ], }; } catch (error) { methodLogger.error( `Error performing YouTube search for query: ${args.query}`, error, ); return formatErrorForMcpTool(error); } }
- src/tools/searchapi.types.ts:77-102 (schema)Zod schema defining the input parameters for the search_youtube tool.export const YouTubeSearchToolArgs = z.object({ query: z.string().describe('The YouTube search query to perform'), // apiKey: z.string().optional().describe('Your SearchAPI.site API key'), maxResults: z .number() .min(1) .max(50) .optional() .describe('Maximum number of results to return (1-50)'), pageToken: z .string() .optional() .describe('Token for pagination to get next/previous page of results'), order: z .enum(['date', 'viewCount', 'rating', 'relevance']) .optional() .describe('Sort order for results'), publishedAfter: z .number() .optional() .describe('Number of days to filter videos from'), videoDuration: z .enum(['short', 'medium', 'long', 'any']) .optional() .describe('Filter by video duration'), });
- src/tools/searchapi.tool.ts:181-191 (registration)Registration of the search_youtube MCP tool with the server, specifying name, description, input schema, and handler function.// Register YouTube search tool server.tool( 'search_youtube', `Performs a YouTube search using SearchAPI.site. Requires a search query and your SearchAPI.site API key. Returns formatted YouTube search results including video titles, thumbnails, descriptions, and links. Supports optional parameters for pagination, sorting, filtering by date and duration. `, YouTubeSearchToolArgs.shape, handleYouTubeSearch, );
- Controller helper function that handles the YouTube search API call to SearchAPI.site service, applies defaults, and formats results.async function youtubeSearch( options: YouTubeSearchOptions, ): Promise<ControllerResponse> { const methodLogger = Logger.forContext( 'controllers/searchapi.controller.ts', 'youtubeSearch', ); methodLogger.debug(`Performing YouTube search for query: ${options.query}`); try { // Validate required parameters if (!options.query) { throw new Error('Query is required for YouTube search'); } const apiKey = config.get('SEARCHAPI_API_KEY'); if (!apiKey) { throw new Error('API key is required for SearchAPI.site'); } // Define controller defaults const defaults: Partial<YouTubeSearchOptions> = { maxResults: 10, order: 'relevance', videoDuration: 'any', }; // Apply defaults to provided options const mergedOptions = applyDefaults<YouTubeSearchOptions>( options, defaults, ); methodLogger.debug('Using options after defaults:', mergedOptions); // Call the service with the options const searchResponse = await searchApiService.youtubeSearch( { query: mergedOptions.query, maxResults: mergedOptions.maxResults, pageToken: mergedOptions.pageToken, order: mergedOptions.order, publishedAfter: mergedOptions.publishedAfter, videoDuration: mergedOptions.videoDuration, }, apiKey, ); methodLogger.debug(`Got the response from the service`, searchResponse); // Format the data using the formatter const formattedContent = formatYouTubeResults(searchResponse); // Return the standard ControllerResponse structure return { content: formattedContent }; } catch (error) { // Use the standardized error handler with return return handleControllerError(error, { entityType: 'YouTube Search Results', operation: 'searching', source: 'controllers/searchapi.controller.ts@youtubeSearch', additionalInfo: { query: options.query }, }); } }