yt-transcript-mcp

YouTube transcripts as token-efficient AI context. One fetch, cached forever.

Agent-first: returns structured JSON by default. Zero dependencies on yt-dlp, ffmpeg, or API keys.

Works with Claude Desktop, ChatGPT Desktop, Cursor, Windsurf, and any MCP client.

Why?

When AI browses YouTube for a transcript, it processes the entire page: navigation, ads, recommendations, scripts. That's 75,000-150,000 tokens of noise to extract maybe 6,000 tokens of actual content.

This tool fetches only the transcript.

~50 KB per video in cache. A year of daily use stays under 120 MB.

Demo

You say:

Fetch the transcript from https://www.youtube.com/watch?v=dQw4w9WgXcQ

Default response (compact JSON, segments only):

{
  "is_error": false,
  "video_id": "dQw4w9WgXcQ",
  "title": "Never Gonna Give You Up",
  "channel": "Rick Astley",
  "published": "2009-10-25",
  "language": "en",
  "caption_type": "manual",
  "segment_count": 56,
  "transcript_duration_seconds": 213.5,
  "content_hash": "a1b2c3...",
  "cache_hit": false,
  "warnings": [],
  "segments": [
    {"text": "We're no strangers to love", "start": 18.0, "end": 21.4},
    {"text": "You know the rules and so do I", "start": 21.4, "end": 24.8}
  ]
}

Structured, machine-readable, one transcript representation. No HTML, no noise, no wasted tokens.

Install

One line. No git clone needed.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "yt-transcript": {
      "command": "uvx",
      "args": ["ytfetch-mcp"]
    }
  }
}

Restart Claude Desktop. Done.

ChatGPT Desktop

Same config in your Codex MCP settings, or add manually:

Tip: Find your uvx path with which uvx. Restart the app after config changes.

Cursor / Windsurf / VS Code

Paste the same JSON block into your MCP server config.

Requires

uv (includes uvx): curl -LsSf https://astral.sh/uv/install.sh | sh

Parameters

Output modes

Markdown format (format=markdown) always renders readable text regardless of output mode.

How it works

• Fetches transcripts directly from YouTube's InnerTube API. No yt-dlp, ffmpeg, browser, Node.js, or API key.
• Tries several YouTube client identities (android_vr, ios, android) and moves to the next only when one is bot-checked or needs a Proof-of-Origin token. A client that was blocked is skipped for 10 minutes.
• Retries only transient failures (HTTP 429, 5xx, timeouts) and never repeats a permanent one.

This relies on YouTube's unofficial client API, so it can need an update when YouTube changes it.

Error handling

Failures are MCP tool errors (isError: true). The result's text is a structured payload with a machine-readable code and a retryable flag, so agents can branch automatically:

{
  "is_error": true,
  "error_code": "VIDEO_UNAVAILABLE",
  "error_message": "Video is unavailable, private, or removed.",
  "retryable": false,
  "retry_count": 0
}

Provenance

Every response includes provenance so you know exactly where the data comes from:

• caption_type: manual, auto-generated, or unknown
• metadata_sources: per-field tracking ({"title": "oembed", "published": "pytubefix"})
• content_hash: SHA256 of the segments array for reproducibility
• warnings: AUTO_GENERATED (speech recognition, may contain errors), LANGUAGE_FALLBACK (got a different language than requested), METADATA_FETCH_FAILED (some metadata unavailable), CLIENT_FALLBACK (an earlier YouTube client was blocked and a later one served the request)

Logging

The server logs to stderr (stdout carries the MCP protocol). Default level is WARNING, which includes client fallbacks and retries. Set YTFETCH_LOG_LEVEL=INFO to also log which YouTube client served each fetch.

Cache

Transcripts cached locally in ~/.cache/yt-transcript/. Keyed by video ID + language preference. Second fetch: instant, zero network.

• Cache entries validated on load (version, types, segments, metadata)
• Legacy or corrupted entries silently skipped
• Cache write failures never block transcript delivery

CLI

Also works standalone, no MCP client needed:

uvx ytfetch-mcp  # starts the MCP server
uv run yt_transcript.py https://youtu.be/ABC123  # CLI mode, saves .md file

CLI flags: --date, --title, --channel, --lang, --out, --no-clean, --no-cache.

Roadmap

• Summary mode -- condensed output for lower token cost
• Token budget (max_tokens) -- fit any context window
• Batch URLs -- multiple videos in one call
• Chapter/topic filtering -- return only relevant sections
• Remote HTTP transport -- expose as streamable HTTP MCP server
• Schema.org metadata -- replace pytubefix for publish date
• MCP outputSchema / structured content
• PO-token fallback -- keep working if YouTube enforces tokens on every client

Support

If this saves you time or tokens:

MIT \u00a9 Bj\u00f6rn Walther