YouTube Transcript DL MCP Server

Instructions

Implementation Reference

• src/server/mcp-server.ts:343-357 (handler)

  MCP tool handler for 'list_transcripts' that validates input, calls the transcript service, and returns formatted JSON response.

  private async handleListTranscripts(args: any) {
    const { videoId } = args;
    
    if (!videoId) {
      throw new McpError(ErrorCode.InvalidParams, 'videoId is required');
    }
  
    const result = await this.transcriptService.listTranscripts(videoId);
    
    return {
      content: [{
        type: 'text',
        text: JSON.stringify(result, null, 2)
      }]
    };

• src/server/mcp-server.ts:222-235 (schema)

  Input schema and metadata definition for the 'list_transcripts' tool.

  {
    name: 'list_transcripts',
    description: 'List all available transcripts for a YouTube video',
    inputSchema: {
      type: 'object',
      properties: {
        videoId: {
          type: 'string',
          description: 'YouTube video ID or URL'
        }
      },
      required: ['videoId']
    }
  }

• src/server/mcp-server.ts:71-72 (registration)

  Registration of the 'list_transcripts' handler in the tool call switch statement.

  case 'list_transcripts':
    return await this.handleListTranscripts(args);

• src/services/youtube-transcript.service.ts:251-284 (helper)

  Helper method in the transcript service that executes the Python script to list transcripts and handles the response.

  public async listTranscripts(videoId: string): Promise<{
    success: boolean;
    videoId: string;
    transcripts: Array<{
      language: string;
      language_code: string;
      is_generated: boolean;
      is_translatable: boolean;
    }>;
    error?: string;
  }> {
    try {
      const cleanVideoId = this.extractVideoId(videoId);
      const command = `python3 "${this.pythonScript}" list --video-id "${cleanVideoId}"`;
      
      const { stdout, stderr } = await execAsync(command);
  
      if (stderr) {
        this.logger.warn(`Python script warning: ${stderr}`);
      }
  
      const result: PythonListResult = JSON.parse(stdout);
      return result;
  
    } catch (error) {
      this.logger.error(`Failed to list transcripts for video ${videoId}:`, error);
      return {
        success: false,
        videoId: this.extractVideoId(videoId),
        transcripts: [],
        error: error instanceof Error ? error.message : 'Unknown error'
      };
    }
  }

• scripts/youtube_transcript_fetcher.py:64-90 (helper)

  Python helper function that uses YouTubeTranscriptApi to list available transcripts for a video.

  def list_transcripts(video_id):
      """List available transcripts for a video"""
      try:
          transcript_list = YouTubeTranscriptApi.list_transcripts(video_id)
          
          transcripts = []
          for transcript in transcript_list:
              transcripts.append({
                  'language': transcript.language,
                  'language_code': transcript.language_code,
                  'is_generated': transcript.is_generated,
                  'is_translatable': transcript.is_translatable
              })
          
          return {
              'success': True,
              'videoId': video_id,
              'transcripts': transcripts
          }
          
      except Exception as e:
          return {
              'success': False,
              'videoId': video_id,
              'error': str(e),
              'transcripts': []
          }