Skip to main content
Glama

yt-transcript — YouTube Transcript MCP Server

Give your AI agent eyes for YouTube. A lightweight youtube transcript mcp server + CLI that fetches the transcript, description, and comments of any YouTube video — so your agent can read, summarize, and analyze video content.

Copy-paste in 30s / Copie e rode em 30s

git clone https://github.com/JADRT22/yt-transcript.git
cd yt-transcript
python3 -m venv .venv
.venv/bin/pip install -e .
.venv/bin/yt-transcript "https://www.youtube.com/watch?v=VIDEO_ID"

🇧🇷 Em Português: servidor MCP + CLI de transcrição do YouTube (youtube transcript mcp server) — busca transcrição, descrição e comentários de qualquer vídeo para seu agente resumir e analisar, com cache em disco e fallback em 4 camadas contra bloqueio do YouTube.

Works with opencode, Claude Code, Freebuff, Cursor, and any MCP-compatible client — or as a plain CLI any agent can call.

Related MCP server: VidLens

Why this one?

YouTube aggressively blocks scripted access ("confirm you're not a bot", HTTP 429). Most transcript tools break the first time YouTube pushes back. This one ships a 4-layer fallback cascade baked in:

Layer

What it does

1. youtube-transcript-api

Fast path, no API key needed

2. yt-dlp web client

Baseline fallback

3. yt-dlp android client

Bypasses the "not a bot" check on most videos

4. yt-dlp + browser cookies

Cures hard IP blocks / 429s (uses your Firefox/Chrome cookies)

Plus:

  • Disk cache (~/.cache/yt-transcript/) — second call for the same video is ~10x faster and consumes zero rate limit

  • Description + comments — likes, authors, replies; great context for richer summaries

  • Language aware — pick preferred languages; lists everything available per video

  • Zero config, zero API keys

Install

git clone https://github.com/JADRT22/yt-transcript.git
cd yt-transcript
python3 -m venv .venv
.venv/bin/pip install -e .

MCP setup

Point your client at the server binary:

/absolute/path/to/yt-transcript/.venv/bin/yt-transcript-mcp

In ~/.config/opencode/opencode.json (global) or opencode.json (project):

{
  "mcp": {
    "yt-transcript": {
      "type": "local",
      "command": ["/absolute/path/to/yt-transcript/.venv/bin/yt-transcript-mcp"],
      "enabled": true
    }
  }
}
claude mcp add yt-transcript -- /absolute/path/to/yt-transcript/.venv/bin/yt-transcript-mcp

Create a mcp.json in the project root where the agent runs:

{
  "mcpServers": {
    "yt-transcript": {
      "command": "/absolute/path/to/yt-transcript/.venv/bin/yt-transcript-mcp"
    }
  }
}

Any agent that runs shell commands can read the output directly:

/absolute/path/to/yt-transcript/.venv/bin/yt-transcript "https://www.youtube.com/watch?v=VIDEO_ID"

MCP tools

Tool

Description

get_transcript_tool(url, languages?)

Full transcript of the video

list_transcripts_tool(url)

Available captions (languages, auto-generated?)

get_video_info_tool(url)

Header facts only: title, channel, duration, upload date

get_video_details_tool(url, max_comments?)

Full description + comments (author, text, likes)

get_video_details_tool is a superset of get_video_info_tool — it returns those same header fields plus the description and comments. Use get_video_info_tool when you just need the basics and want the fastest call.

Example prompts once connected:

Summarize this video: https://www.youtube.com/watch?v=...

What are people saying in the comments of this video? [URL]

Compare what the video claims with what the description promises: [URL]

CLI usage

# Full transcript (default languages: en, es, pt)
.venv/bin/yt-transcript "https://www.youtube.com/watch?v=VIDEO_ID"

# Metadata only
.venv/bin/yt-transcript VIDEO_ID --info

# Description + comments (JSON)
.venv/bin/yt-transcript VIDEO_ID --desc --max-comments 50

# Available captions
.venv/bin/yt-transcript VIDEO_ID --list

# JSON output / other languages
.venv/bin/yt-transcript VIDEO_ID --json
.venv/bin/yt-transcript VIDEO_ID -l de,fr

Accepts youtube.com/watch?v=..., youtu.be/..., youtube.com/shorts/..., or the bare 11-character ID.

Configuration

Environment variable

Default

Purpose

YT_TRANSCRIPT_COOKIES_BROWSER

firefox

Browser for the cookie fallback (chrome, chromium, brave, ...; none disables)

YT_TRANSCRIPT_CACHE

~/.cache/yt-transcript

Cache directory (none disables)

To force a fresh fetch for one video, delete its file (SHA-256-named) from the cache directory.

How it works

  1. extract_video_id normalizes any YouTube URL format into a video ID.

  2. Transcripts: captions API first; on any failure, yt-dlp downloads the .vtt through the client cascade and converts it to plain text (each attempt only counts if the caption file is actually written — yt-dlp's simulation mode silently skips it, and --no-simulate guards that).

  3. Metadata/details: yt-dlp --print / --dump-json --write-comments through the same cascade.

  4. Everything is cached on disk; agents can retry cheaply.

Limitations

  • Videos with no captions at all can't be transcripted (no Whisper/ASR — this tool stays lightweight on purpose).

  • Browser-cookie access requires the target browser installed locally; in logged-in sessions YouTube sometimes serves empty format lists to yt-dlp, which is exactly why cookies are the last layer (and always paired with --ignore-no-formats-error).

  • Cache is content-blind: if a video's description/comments change, clear the cache entry.

License

MIT © 2026 JADRT22

Available Tools

4 tools
get_transcript_toolB

Returns the full transcript of a YouTube video.

Args: url: Video URL (youtube.com/watch?v=..., youtu.be/..., shorts/...) or ID. languages: Preferred language codes, comma-separated (e.g. "en,es,pt"). Defaults to the server default.

Returns: Transcript text with a metadata header, or an error message.

Inputs: url (required), languages. Returns: result

get_video_details_toolA

Returns title, channel, duration, FULL description and comments of a video.

Useful for understanding context, mentioned links and audience reception.

Args: url: Video URL or ID. max_comments: maximum number of comments (default 50).

Returns: JSON with description and a comments list (author, text, likes).

Inputs: url (required), max_comments. Returns: result

get_video_info_toolC

Returns video metadata: title, channel, duration and upload date.

Inputs: url (required). Returns: result

list_transcripts_toolA

Lists the captions/transcripts available for a video (languages and type).

Inputs: url (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 4 tools

    Disambiguation3/5

    get_video_details_tool and get_video_info_tool overlap heavily, both returning title, channel and duration; the distinction (details adds description/comments, info adds upload date) is only implicit. get_transcript_tool and list_transcripts_tool are clearly separable, but the two metadata tools risk misselection.

    Naming Consistency5/5

    All four tools follow a consistent verb_noun_tool pattern (get_video_details_tool, get_transcript_tool, list_transcripts_tool, get_video_info_tool) with uniform snake_case. Naming is highly predictable.

    Tool Count4/5

    Four tools are well-scoped for a YouTube transcript/metadata server, each targeting a distinct operation. Slightly thin, and the count is partly inflated by two near-duplicate metadata tools that could be merged.

    Completeness4/5

    The surface covers listing available transcripts, fetching a transcript, retrieving metadata, and gathering description/comments, which spans the core domain lifecycle. No update/delete is needed for a read-only extractor, so coverage is solid with only minor gaps (e.g. no bulk or search operation).

    Maintenance

    ActivitySlowing
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers