mcp-server-youtube-transcript

Instructions

Implementation Reference

• src/index.ts:16-60 (registration)

  Defines the MCP Tool object for 'get_transcript' including name, description, inputSchema, outputSchema, and annotations. Used for both listing tools and validation.
  const TOOLS: Tool[] = [ { name: "get_transcript", description: "Extract transcript from a YouTube video URL or ID. Automatically falls back to available languages if requested language is not available.", inputSchema: { type: "object", properties: { url: { type: "string", description: "YouTube video URL or ID" }, lang: { type: "string", description: "Language code for transcript (e.g., 'ko', 'en'). Will fall back to available language if not found.", default: "en" }, include_timestamps: { type: "boolean", description: "Include timestamps in output (e.g., '[0:05] text'). Useful for referencing specific moments. Default: false", default: false }, strip_ads: { type: "boolean", description: "Filter out sponsored segments from transcript based on chapter markers (e.g., chapters marked as 'Werbung', 'Ad', 'Sponsor'). Default: true", default: true } }, required: ["url"] }, // OutputSchema describes structuredContent format for Claude Code outputSchema: { type: "object", properties: { meta: { type: "string", description: "Title | Author | Subs | Views | Date" }, content: { type: "string" } }, required: ["content"] }, annotations: { title: "Get Transcript", readOnlyHint: true, openWorldHint: true, }, }, ];
• src/index.ts:261-325 (handler)

  Primary handler logic for executing the 'get_transcript' tool in response to CallToolRequest. Validates input, extracts video ID, fetches and processes transcript, adds informational notes about language fallback and ad stripping, returns structured MCP response.
  case "get_transcript": { const { url: input, lang = "en", include_timestamps = false, strip_ads = true } = args; if (!input || typeof input !== 'string') { throw new McpError( ErrorCode.InvalidParams, 'URL parameter is required and must be a string' ); } if (lang && typeof lang !== 'string') { throw new McpError( ErrorCode.InvalidParams, 'Language code must be a string' ); } try { const videoId = this.extractor.extractYoutubeId(input); console.log(`Processing transcript for video: ${videoId}, lang: ${lang}, timestamps: ${include_timestamps}, strip_ads: ${strip_ads}`); const result = await this.extractor.getTranscript(videoId, lang, include_timestamps, strip_ads); console.log(`Successfully extracted transcript (${result.text.length} chars, lang: ${result.actualLang}, ads stripped: ${result.adsStripped})`); // Build transcript with notes let transcript = result.text; // Add language fallback notice if different from requested if (result.actualLang !== lang) { transcript = `[Note: Requested language '${lang}' not available. Using '${result.actualLang}'. Available: ${result.availableLanguages.join(', ')}]\n\n${transcript}`; } // Add ad filtering notice based on what happened if (result.adsStripped > 0) { // Ads were filtered by chapter markers transcript = `[Note: ${result.adsStripped} sponsored segment lines filtered out based on chapter markers]\n\n${transcript}`; } else if (strip_ads && result.adChaptersFound === 0) { // No chapter markers found - add prompt hint as fallback transcript += '\n\n[Note: No chapter markers found. If summarizing, please exclude any sponsored segments or ads from the summary.]'; } // Claude Code v2.0.21+ needs structuredContent for proper display return { content: [{ type: "text" as const, text: transcript }], structuredContent: { meta: `${result.metadata.title} | ${result.metadata.author} | ${result.metadata.subscriberCount} subs | ${result.metadata.viewCount} views | ${result.metadata.publishDate}`, content: transcript.replace(/[\r\n]+/g, ' ').replace(/\s+/g, ' ') } }; } catch (error) { console.error('Transcript extraction failed:', error); if (error instanceof McpError) { throw error; } throw new McpError( ErrorCode.InternalError, `Failed to process transcript: ${(error as Error).message}` ); } }
• src/index.ts:127-182 (helper)

  Helper method in YouTubeTranscriptExtractor class that fetches subtitles using getSubtitles, strips ad segments based on chapters if requested, formats the transcript text, and returns processed result with metadata.
  async getTranscript(videoId: string, lang: string, includeTimestamps: boolean, stripAds: boolean): Promise<{ text: string; actualLang: string; availableLanguages: string[]; adsStripped: number; adChaptersFound: number; metadata: { title: string; author: string; subscriberCount: string; viewCount: string; publishDate: string; }; }> { try { const result = await getSubtitles({ videoID: videoId, lang: lang, enableFallback: true, }); let lines = result.lines; let adsStripped = 0; // Filter out lines that fall within ad chapters if (stripAds && result.adChapters.length > 0) { const originalCount = lines.length; lines = lines.filter(line => { const lineStartMs = line.start * 1000; // Check if this line falls within any ad chapter return !result.adChapters.some((ad: AdChapter) => lineStartMs >= ad.startMs && lineStartMs < ad.endMs ); }); adsStripped = originalCount - lines.length; if (adsStripped > 0) { console.log(`[youtube-transcript] Filtered ${adsStripped} lines from ${result.adChapters.length} ad chapter(s): ${result.adChapters.map((a: AdChapter) => a.title).join(', ')}`); } } return { text: this.formatTranscript(lines, includeTimestamps), actualLang: result.actualLang, availableLanguages: result.availableLanguages.map((t: CaptionTrack) => t.languageCode), adsStripped, adChaptersFound: result.adChapters.length, metadata: result.metadata }; } catch (error) { console.error('Failed to fetch transcript:', error); throw new McpError( ErrorCode.InternalError, `Failed to retrieve transcript: ${(error as Error).message}` ); } }
• src/index.ts:187-208 (helper)

  Formats transcript lines into readable string, optionally with timestamps in [m:ss] or [h:mm:ss] format.
  private formatTranscript(transcript: TranscriptLine[], includeTimestamps: boolean): string { if (includeTimestamps) { return transcript .map(line => { const totalSeconds = Math.floor(line.start); const hours = Math.floor(totalSeconds / 3600); const mins = Math.floor((totalSeconds % 3600) / 60); const secs = totalSeconds % 60; // Use h:mm:ss for videos > 1 hour, mm:ss otherwise const timestamp = hours > 0 ? `[${hours}:${mins.toString().padStart(2, '0')}:${secs.toString().padStart(2, '0')}]` : `[${mins}:${secs.toString().padStart(2, '0')}]`; return `${timestamp} ${line.text.trim()}`; }) .filter(text => text.length > 0) .join('\n'); } return transcript .map(line => line.text.trim()) .filter(text => text.length > 0) .join(' '); }
• src/youtube-fetcher.ts:273-403 (helper)

  Core helper function that implements YouTube transcript fetching via internal /youtubei/v1/get_transcript API endpoint using protobuf-encoded parameters, visitorData auth, language fallback, page data extraction for captions/chapters/metadata.
  export async function getSubtitles(options: { videoID: string; lang?: string; enableFallback?: boolean; }): Promise<SubtitleResult> { const { videoID, lang = 'en', enableFallback = true } = options; // Validate video ID format if (!videoID || typeof videoID !== 'string') { throw new Error('Invalid video ID: must be a non-empty string'); } // Get page data (visitor data needed for API authentication) const { visitorData, availableLanguages, adChapters, metadata } = await getPageData(videoID); // Determine which language to use let targetLang = lang; if (availableLanguages.length > 0) { const hasRequestedLang = availableLanguages.some(t => t.languageCode === lang); if (!hasRequestedLang && enableFallback) { // Try English first const hasEnglish = availableLanguages.some(t => t.languageCode === 'en'); if (hasEnglish) { targetLang = 'en'; console.error(`[youtube-fetcher] Language '${lang}' not available, falling back to 'en'`); } else { // Use first available targetLang = availableLanguages[0].languageCode; console.error(`[youtube-fetcher] Language '${lang}' not available, falling back to '${targetLang}'`); } } else if (!hasRequestedLang) { throw new Error(`Language '${lang}' not available. Available: ${availableLanguages.map(t => t.languageCode).join(', ')}`); } } // Build request payload using ANDROID client to avoid FAILED_PRECONDITION errors // The ANDROID client bypasses YouTube's A/B test for poToken enforcement const params = buildParams(videoID, targetLang); const payload = JSON.stringify({ context: { client: { hl: targetLang, gl: 'US', clientName: 'ANDROID', clientVersion: ANDROID_CLIENT_VERSION, androidSdkVersion: 30, visitorData: visitorData } }, params: params }); // Make API request let response: string; try { response = await httpsRequest({ hostname: 'www.youtube.com', path: '/youtubei/v1/get_transcript?prettyPrint=false', method: 'POST', headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload), 'User-Agent': ANDROID_USER_AGENT, 'Origin': 'https://www.youtube.com' } }, payload); } catch (err) { throw new Error(`Failed to fetch transcript API: ${(err as Error).message}`); } // Parse response with error handling let json: any; try { json = JSON.parse(response); } catch (err) { throw new Error(`Failed to parse YouTube API response: ${(err as Error).message}. Response preview: ${response.substring(0, 200)}`); } // Check for API-level errors if (json.error) { const errorMsg = json.error.message || json.error.code || 'Unknown API error'; throw new Error(`YouTube API error: ${errorMsg}`); } // Extract transcript segments - handle both WEB and ANDROID response formats const webSegments = json?.actions?.[0]?.updateEngagementPanelAction?.content ?.transcriptRenderer?.content?.transcriptSearchPanelRenderer?.body ?.transcriptSegmentListRenderer?.initialSegments; const androidSegments = json?.actions?.[0]?.elementsCommand?.transformEntityCommand ?.arguments?.transformTranscriptSegmentListArguments?.overwrite?.initialSegments; const segments = webSegments || androidSegments || []; if (segments.length === 0) { throw new Error('No transcript available for this video. The video may not have captions enabled.'); } // Convert to TranscriptLine format const lines = segments .filter((seg: any) => seg?.transcriptSegmentRenderer) // Skip section headers .map((seg: any) => { const renderer = seg.transcriptSegmentRenderer; // Handle both WEB format (snippet.runs) and ANDROID format (snippet.elementsAttributedString) const webText = renderer?.snippet?.runs?.map((r: any) => r.text || '').join(''); const androidText = renderer?.snippet?.elementsAttributedString?.content; const text = webText || androidText || ''; const startMs = parseInt(renderer?.startMs || '0', 10); const endMs = parseInt(renderer?.endMs || '0', 10); return { text: text, start: startMs / 1000, dur: (endMs - startMs) / 1000 }; }) .filter((line: TranscriptLine) => line.text.length > 0); return { lines, requestedLang: lang, actualLang: targetLang, availableLanguages, adChapters, metadata }; }