YouTube Transcript DL MCP Server

Instructions

Implementation Reference

• src/services/youtube-transcript.service.ts:223-249 (handler)

  Primary handler function implementing the core logic for fetching transcripts from a YouTube playlist (currently a stub requiring YouTube Data API integration)

  public async getPlaylistTranscripts(
    request: PlaylistTranscriptRequest
  ): Promise<BulkTranscriptResponse> {
    try {
      // Extract playlist ID
      const playlistId = this.extractPlaylistId(request.playlistId);
      
      // Get video IDs from playlist (this would need YouTube Data API)
      // For now, we'll throw an error indicating this needs API key
      throw new Error('Playlist processing requires YouTube Data API key. Please extract video IDs manually.');
      
    } catch (error) {
      this.logger.error(`Failed to process playlist ${request.playlistId}:`, error);
      return {
        results: [],
        errors: [{
          videoId: request.playlistId,
          error: error instanceof Error ? error.message : 'Unknown error'
        }],
        summary: {
          total: 0,
          successful: 0,
          failed: 1
        }
      };
    }
  }

• src/server/mcp-server.ts:280-302 (handler)

  MCP server-side handler that validates input, constructs the request, calls the transcript service, and formats the MCP response

  private async handleGetPlaylistTranscripts(args: any) {
    const { playlistId, language = 'en', outputFormat = 'json', includeMetadata = true } = args;
    
    if (!playlistId) {
      throw new McpError(ErrorCode.InvalidParams, 'playlistId is required');
    }
  
    const request = {
      playlistId,
      language,
      outputFormat,
      includeMetadata
    };
  
    const result = await this.transcriptService.getPlaylistTranscripts(request);
    
    return {
      content: [{
        type: 'text',
        text: JSON.stringify(result, null, 2)
      }]
    };
  }

• src/server/mcp-server.ts:149-177 (registration)

  Tool registration in the MCP server's available tools list, including description and input schema

    name: 'get_playlist_transcripts',
    description: 'Extract transcripts from all videos in a YouTube playlist',
    inputSchema: {
      type: 'object',
      properties: {
        playlistId: {
          type: 'string',
          description: 'YouTube playlist ID or URL'
        },
        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: ['playlistId']
    }
  },

• src/types/index.ts:40-45 (schema)

  TypeScript interface defining the input parameters for the getPlaylistTranscripts method

  export interface PlaylistTranscriptRequest {
    playlistId: string;
    outputFormat: 'text' | 'json' | 'srt';
    language?: string;
    includeMetadata?: boolean;
  }

• src/types/index.ts:27-38 (schema)

  TypeScript interface defining the output response structure for bulk/playlist transcript requests

  export interface BulkTranscriptResponse {
    results: TranscriptResponse[];
    errors: Array<{
      videoId: string;
      error: string;
    }>;
    summary: {
      total: number;
      successful: number;
      failed: number;
    };
  }