| name | youtube-transcript |
| description | Fetch the spoken transcript (captions) of a YouTube video or Short. Use when the user gives a YouTube URL or video ID and wants the transcript, captions, spoken-content summary, or quotes from a video. Trigger with phrases like "get the transcript", "transcribe this YouTube video", or "what does this video say". |
YouTube Transcript
Fetch the spoken transcript (captions) from a YouTube video or Short.
How to run
python3 ${CLAUDE_PLUGIN_ROOT}/skills/youtube-transcript/scripts/fetch_transcript.py \
<url-or-id> [--timestamps] [--lang en] [--proxy URL] [--cookies cookies.txt] \
[--no-check-certs] [--out file.txt]
Requirements
yt-dlp (>= 2025.x): pip install yt-dlp- Recommended:
deno JS runtime for clean extraction.
- Behind a TLS-intercepting proxy, pass
--no-check-certs.
Credentials (set once, auto-applied)
From a datacenter IP YouTube often bot-gates or 429s. Rather than re-passing flags every
call, configure credentials once — the script resolves them with precedence
flag > env var > file:
| Env var | Effect | Flag equivalent |
|---|
YT_TRANSCRIPT_PROXY (or HTTPS_PROXY) | route via proxy | --proxy |
YT_TRANSCRIPT_COOKIES | path to a Netscape cookies.txt | --cookies |
YT_TRANSCRIPT_NO_CHECK_CERTS=1 | disable cert checks | --no-check-certs |
A cookies.txt dropped in ${CLAUDE_PLUGIN_ROOT} or beside the script is auto-detected.
Security: secrets are read from the environment/files only — never hard-code or commit
them. cookies.txt/.env are git-ignored. For the MCP server (mcp-server/), set these on
the server's launch env so they never appear at the call site.
Why naive approaches break
- Parsing
ytInitialPlayerResponse from HTML returns empty captionTracks. Never do this.
- Default web/android InnerTube clients return zero tracks. Script forces
player_client=android_vr,tv,web via --extractor-args.
timedtext endpoint returns HTTP 429 from datacenter IPs. Script retries
with exponential backoff; for hard blocks use --proxy or --cookies.
Exit codes
0 success · 2 no captions · 3 rate-limited (use --proxy/--cookies) · 4 yt-dlp missing.
