videos_searchVideos
Search YouTube videos using queries to find and retrieve video results with URLs for content discovery.
Instructions
Search for videos on YouTube and return results with URLs
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query | |
| maxResults | No | Maximum number of results to return |
Implementation Reference
- src/services/video.ts:84-103 (handler)Core handler function implementing YouTube video search using googleapis YouTube Data API v3, initializes client, performs search.list, structures results with video URLs using helper.async searchVideos({ query, maxResults = 10 }: SearchParams): Promise<unknown[]> { try { this.initialize(); const response = await this.youtube.search.list({ part: ['snippet'], q: query, maxResults, type: ['video'] }); const videos = response.data.items || []; return this.createStructuredVideos(videos); } catch (error) { throw new Error(`Failed to search videos: ${error instanceof Error ? error.message : String(error)}`); } }
- src/types.ts:10-15 (schema)TypeScript interface defining input parameters for the videos_searchVideos tool (query, optional maxResults).* Search videos parameters */ export interface SearchParams { query: string; maxResults?: number; }
- src/server-utils.ts:154-174 (registration)MCP tool registration including name, zod-based input schema (matching SearchParams type), thin wrapper handler calling VideoService.searchVideos, and JSON response formatting.server.registerTool( 'videos_searchVideos', { title: 'Search Videos', description: 'Search for videos on YouTube and return results with URLs', annotations: { readOnlyHint: true, idempotentHint: true }, inputSchema: { query: z.string().describe('Search query'), maxResults: z.number().optional().describe('Maximum number of results to return'), }, }, async ({ query, maxResults }) => { const result = await videoService.searchVideos({ query, maxResults }); return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] }; } );
- src/services/video.ts:36-38 (helper)Helper utility to transform raw YouTube API video search results into structured objects including computed videoId and full YouTube watch URL.private createStructuredVideos(videos: unknown[]): unknown[] { return videos.map(video => this.createStructuredVideo(video)).filter(Boolean); }
- src/services/video.ts:18-31 (helper)Helper utility to add videoId and canonical YouTube URL to individual video objects from API responses.private createStructuredVideo(videoData: unknown): unknown { if (!videoData) return null; // eslint-disable-next-line @typescript-eslint/no-explicit-any const v = videoData as any; const videoId = v.id || v.id?.videoId; const url = videoId ? `https://www.youtube.com/watch?v=${videoId}` : null; return { ...v, url, videoId }; }