mcp-youtube-transcript

Instructions

Implementation Reference

• src/index.ts:68-107 (handler)

  Primary handler function for the 'get_transcripts' tool. Extracts video ID from URL, fetches transcripts using the extractor, formats the text, and returns structured content with title and metadata.
  async (input) => { try { const videoId = this.extractor.extractYoutubeId(input.url); console.error(`Processing transcripts for video: ${videoId}`); const { transcripts, title } = await this.extractor.getTranscripts({ videoID: videoId, lang: input.lang }); // Format text with optional paragraph breaks const formattedText = YouTubeUtils.formatTranscriptText(transcripts, { enableParagraphs: input.enableParagraphs }); console.error(`Successfully extracted transcripts for "${title}" (${formattedText.length} chars)`); return { content: [{ type: "text", text: `# ${title}\n\n${formattedText}`, metadata: { videoId, title, language: input.lang, timestamp: new Date().toISOString(), charCount: formattedText.length, transcriptCount: transcripts.length, totalDuration: YouTubeUtils.calculateTotalDuration(transcripts), paragraphsEnabled: input.enableParagraphs } }] }; } catch (error) { if (error instanceof YouTubeTranscriptError || error instanceof McpError) { throw error; } throw new YouTubeTranscriptError(`Failed to process transcripts: ${(error as Error).message}`); } }
• src/index.ts:63-67 (schema)

  Zod input schema definition for the tool parameters: url (required), lang (optional), enableParagraphs (optional).
  { url: z.string().describe("YouTube video URL or ID"), lang: z.string().default("en").describe("Language code for transcripts, default 'en' (e.g. 'en', 'uk', 'ja', 'ru', 'zh')"), enableParagraphs: z.boolean().default(false).describe("Enable automatic paragraph breaks, default `false`") },
• src/index.ts:60-108 (registration)

  Registration of the 'get_transcripts' tool with the MCP server, specifying name, description, input schema, and handler function.
  this.server.tool( "get_transcripts", `Extract and process transcripts from a YouTube video.\n\n**Parameters:**\n- \`url\` (string, required): YouTube video URL or ID.\n- \`lang\` (string, optional, default 'en'): Language code for transcripts (e.g. 'en', 'uk', 'ja', 'ru', 'zh').\n- \`enableParagraphs\` (boolean, optional, default false): Enable automatic paragraph breaks.\n\n**IMPORTANT:** If the user does *not* specify a language *code*, **DO NOT** include the \`lang\` parameter in the tool call. Do not guess the language or use parts of the user query as the language code.`, { url: z.string().describe("YouTube video URL or ID"), lang: z.string().default("en").describe("Language code for transcripts, default 'en' (e.g. 'en', 'uk', 'ja', 'ru', 'zh')"), enableParagraphs: z.boolean().default(false).describe("Enable automatic paragraph breaks, default `false`") }, async (input) => { try { const videoId = this.extractor.extractYoutubeId(input.url); console.error(`Processing transcripts for video: ${videoId}`); const { transcripts, title } = await this.extractor.getTranscripts({ videoID: videoId, lang: input.lang }); // Format text with optional paragraph breaks const formattedText = YouTubeUtils.formatTranscriptText(transcripts, { enableParagraphs: input.enableParagraphs }); console.error(`Successfully extracted transcripts for "${title}" (${formattedText.length} chars)`); return { content: [{ type: "text", text: `# ${title}\n\n${formattedText}`, metadata: { videoId, title, language: input.lang, timestamp: new Date().toISOString(), charCount: formattedText.length, transcriptCount: transcripts.length, totalDuration: YouTubeUtils.calculateTotalDuration(transcripts), paragraphsEnabled: input.enableParagraphs } }] }; } catch (error) { if (error instanceof YouTubeTranscriptError || error instanceof McpError) { throw error; } throw new YouTubeTranscriptError(`Failed to process transcripts: ${(error as Error).message}`); } } );
• src/index.ts:20-33 (helper)

  Helper method in YouTubeTranscriptExtractor class that wraps the core fetchTranscripts call and adds error handling.
  async getTranscripts({ videoID, lang }: TranscriptOptions): Promise<{ transcripts: Transcript[], title: string }> { try { const result = await YouTubeTranscriptFetcher.fetchTranscripts(videoID, { lang }); if (result.transcripts.length === 0) { throw new YouTubeTranscriptError('No transcripts found'); } return result; } catch (error) { if (error instanceof YouTubeTranscriptError || error instanceof McpError) { throw error; } throw new YouTubeTranscriptError(`Failed to fetch transcripts: ${(error as Error).message}`); } }
• src/youtube.ts:421-436 (helper)

  Core helper function in YouTubeTranscriptFetcher that extracts video ID, fetches transcript config/content and title concurrently, representing the main implementation logic for retrieving transcripts.
  static async fetchTranscripts(videoId: string, config?: { lang?: string }): Promise<{ transcripts: Transcript[], title: string }> { try { const identifier = this.extractVideoId(videoId); const [{ transcripts }, title] = await Promise.all([ this.fetchTranscriptConfigAndContent(identifier, config?.lang), this.fetchVideoTitle(identifier) ]); return { transcripts, title }; } catch (error) { if (error instanceof YouTubeTranscriptError || error instanceof McpError) { throw error; } throw new YouTubeTranscriptError(`Failed to fetch transcripts: ${(error as Error).message}`); } }