YouTube Transcript DL MCP Server

Instructions

Implementation Reference

• src/server/mcp-server.ts:239-254 (handler)

  MCP tool handler for 'get_transcript'. Validates args, calls YouTubeTranscriptService.getTranscript, formats response as MCP content with JSON text.

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

• src/server/mcp-server.ts:92-116 (registration)

  Registration of the 'get_transcript' tool in the listTools response, including name, description, and input schema definition.

  {
    name: 'get_transcript',
    description: 'Extract transcript from a single YouTube video',
    inputSchema: {
      type: 'object',
      properties: {
        videoId: {
          type: 'string',
          description: 'YouTube video ID or URL'
        },
        language: {
          type: 'string',
          description: 'Language code (e.g., "en", "es", "fr")',
          default: 'en'
        },
        format: {
          type: 'string',
          enum: ['text', 'json', 'srt'],
          description: 'Output format',
          default: 'json'
        }
      },
      required: ['videoId']
    }
  },

• src/server/mcp-server.ts:92-116 (schema)

  Input schema and metadata for the 'get_transcript' tool used for validation in MCP listTools.

  {
    name: 'get_transcript',
    description: 'Extract transcript from a single YouTube video',
    inputSchema: {
      type: 'object',
      properties: {
        videoId: {
          type: 'string',
          description: 'YouTube video ID or URL'
        },
        language: {
          type: 'string',
          description: 'Language code (e.g., "en", "es", "fr")',
          default: 'en'
        },
        format: {
          type: 'string',
          enum: ['text', 'json', 'srt'],
          description: 'Output format',
          default: 'json'
        }
      },
      required: ['videoId']
    }
  },

• src/services/youtube-transcript.service.ts:80-154 (helper)

  Core helper function implementing transcript extraction logic: caching, video ID extraction, Python script execution for fetching transcript data from YouTube, result processing, error handling.

  public async getTranscript(
    videoId: string,
    language: string = 'en',
    format: 'text' | 'json' | 'srt' = 'json'
  ): Promise<TranscriptResponse> {
    try {
      // Clean video ID from URL if needed
      const cleanVideoId = this.extractVideoId(videoId);
      const cacheKey = `transcript:${cleanVideoId}:${language}:${format}`;
  
      // Check cache first
      const cached = this.cache.get<TranscriptResponse>(cacheKey);
      if (cached) {
        this.logger.debug(`Cache hit for video ${cleanVideoId}`);
        return cached;
      }
  
      this.logger.info(`Fetching transcript for video: ${cleanVideoId}`);
  
      // Call Python script to get transcript
      const command = `python3 "${this.pythonScript}" fetch --video-id "${cleanVideoId}" --language "${language}"`;
      const { stdout, stderr } = await execAsync(command);
  
      if (stderr) {
        this.logger.warn(`Python script warning: ${stderr}`);
      }
  
      const pythonResult: PythonTranscriptResult = JSON.parse(stdout);
  
      if (!pythonResult.success) {
        throw new Error(pythonResult.error || 'Failed to fetch transcript');
      }
  
      // Convert to our format
      const transcript: TranscriptItem[] = pythonResult.transcript.map(item => ({
        text: item.text,
        start: item.start,
        duration: item.duration
      }));
  
      const response: TranscriptResponse = {
        videoId: cleanVideoId,
        title: await this.getVideoTitle(cleanVideoId), // Try to get title
        language,
        transcript,
        metadata: {
          extractedAt: new Date().toISOString(),
          source: 'youtube-transcript-api',
          duration: pythonResult.metadata?.duration || transcript.reduce((acc, item) => acc + item.duration, 0)
        }
      };
  
      // Cache the response
      this.cache.set(cacheKey, response);
  
      this.logger.info(`Successfully extracted transcript for video ${cleanVideoId}`);
      return response;
  
    } catch (error) {
      this.logger.error(`Failed to extract transcript for video ${videoId}:`, error);
      
      // Return structured error response
      return {
        videoId: this.extractVideoId(videoId),
        title: 'Error',
        language,
        transcript: [],
        metadata: {
          extractedAt: new Date().toISOString(),
          source: 'youtube-transcript-api',
          error: error instanceof Error ? error.message : 'Unknown error'
        }
      };
    }
  }