YouTube Transcript DL MCP Server

Instructions

Implementation Reference

• src/server/mcp-server.ts:256-278 (handler)

  The main handler function for the 'get_bulk_transcripts' tool in the MCP server. It validates input, constructs the request object, delegates to the transcript service, and returns a formatted MCP response.
  private async handleGetBulkTranscripts(args: any) { const { videoIds, language = 'en', outputFormat = 'json', includeMetadata = true } = args; if (!videoIds || !Array.isArray(videoIds) || videoIds.length === 0) { throw new McpError(ErrorCode.InvalidParams, 'videoIds array is required'); } const request = { videoIds, language, outputFormat, includeMetadata }; const result = await this.transcriptService.getBulkTranscripts(request); return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] }; }
• src/server/mcp-server.ts:117-147 (registration)

  Registration of the 'get_bulk_transcripts' tool in the server's list of available tools, defining its metadata and input schema for the MCP ListTools request.
  { name: 'get_bulk_transcripts', description: 'Extract transcripts from multiple YouTube videos', inputSchema: { type: 'object', properties: { videoIds: { type: 'array', items: { type: 'string' }, description: 'Array of YouTube video IDs or URLs' }, language: { type: 'string', description: 'Language code (e.g., "en", "es", "fr")', default: 'en' }, outputFormat: { type: 'string', enum: ['text', 'json', 'srt'], description: 'Output format', default: 'json' }, includeMetadata: { type: 'boolean', description: 'Include metadata in response', default: true } }, required: ['videoIds'] } },
• src/types/index.ts:20-38 (schema)

  TypeScript type definitions for the BulkTranscriptRequest (input) and BulkTranscriptResponse (output) used by the tool implementation.
  export interface BulkTranscriptRequest { videoIds: string[]; outputFormat: 'text' | 'json' | 'srt'; language?: string; includeMetadata?: boolean; } export interface BulkTranscriptResponse { results: TranscriptResponse[]; errors: Array<{ videoId: string; error: string; }>; summary: { total: number; successful: number; failed: number; }; }
• src/services/youtube-transcript.service.ts:156-221 (helper)

  Helper service method containing the core logic for fetching bulk transcripts. It invokes a Python script for extraction, processes the results, handles errors, and returns structured responses.
  public async getBulkTranscripts( request: BulkTranscriptRequest ): Promise<BulkTranscriptResponse> { try { this.logger.info(`Processing bulk request for ${request.videoIds.length} videos`); // Call Python script for bulk processing const videoIds = request.videoIds.map(id => this.extractVideoId(id)).join(','); const command = `python3 "${this.pythonScript}" bulk --video-ids "${videoIds}" --language "${request.language || 'en'}"`; const { stdout, stderr } = await execAsync(command); if (stderr) { this.logger.warn(`Python script warning: ${stderr}`); } const pythonResult: PythonBulkResult = JSON.parse(stdout); if (!pythonResult.success) { throw new Error('Bulk processing failed'); } // Convert results to our format const results: TranscriptResponse[] = []; for (const result of pythonResult.results) { const transcript: TranscriptItem[] = result.transcript.map(item => ({ text: item.text, start: item.start, duration: item.duration })); results.push({ videoId: result.videoId, title: await this.getVideoTitle(result.videoId), language: result.language, transcript, metadata: { extractedAt: new Date().toISOString(), source: 'youtube-transcript-api', duration: result.metadata?.duration || transcript.reduce((acc, item) => acc + item.duration, 0) } }); } return { results, errors: pythonResult.errors, summary: pythonResult.summary }; } catch (error) { this.logger.error(`Failed to process bulk request:`, error); return { results: [], errors: request.videoIds.map(videoId => ({ videoId: this.extractVideoId(videoId), error: error instanceof Error ? error.message : 'Unknown error' })), summary: { total: request.videoIds.length, successful: 0, failed: request.videoIds.length } }; } }