Skip to main content
Glama
pobibibi

youtube-transcript-mcp

by pobibibi
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
TypeScript
Local

youtube-transcript-mcp

Turn any YouTube video into a Markdown transcript your LLM can actually afford to read.

CI License: MIT Node TypeScript MCP

The problem

Ask an assistant about a 40-minute talk and it has to swallow the whole thing: ten thousand words of context, most of which answer nothing. Pay for it again next time you ask.

youtube-transcript-mcp puts the transcript on disk and hands back a receipt.

Transcript saved to: transcripts/But what is a neural network.md
Title:    But what is a neural network? | Deep learning chapter 1
Channel:  3Blue1Brown · 18:40 · manual en captions
Words:    3,357     Sections: 12
  - 0:00 — Introduction example
  - 1:07 — Series preview
  - 2:42 — What are neurons?
  ...

That summary is about 50 tokens. The model reads the file when it needs the content — and because the index lists every chapter with its offset, it can read only the chapter that answers the question. A 3,357-word video costs 50 tokens to know about and a few hundred to answer from.

The transcription itself costs nothing: it happens on your machine, not in the model.

Related MCP server: YouTube Transcript MCP Server

What the Markdown looks like

---
title: "But what is a neural network? | Deep learning chapter 1"
channel: "3Blue1Brown"
url: "https://www.youtube.com/watch?v=aircAruvnKk"
video_id: "aircAruvnKk"
duration: "18:40"
published: 2017-10-05
language: "en"
captions: manual
words: 3357
sections: 12
generated: 2026-08-05
---

# But what is a neural network? | Deep learning chapter 1

> **3Blue1Brown** · 18:40 · 2017-10-05 · [Watch on YouTube](...)
>
> Transcribed from manual `en` captions.

## Index

- [0:00](...&t=0) — Introduction example
- [1:07](...&t=67) — Series preview
- [2:42](...&t=162) — What are neurons?

## Transcript

### [0:00](...&t=0) Introduction example

**[0:04]** This is a 3. It's sloppily written and rendered at an extremely low
resolution of 28x28 pixels, but your brain has no trouble recognizing it as a 3...

Every design choice in that file exists to make it cheap to navigate:

Choice

Why

YAML front matter

The model can cite the source without opening anything else.

Author's chapters as ### sections

Real semantic boundaries, written by someone who watched the video.

No chapters → 5-minute blocks

Still gives the model somewhere to aim.

&t= links on every heading

One click opens YouTube at that exact second.

Timestamps per paragraph

An answer can point at when something was said.

Paragraphs, not caption lines

Captions break every 3 seconds; prose doesn't.

Install

Requires Node.js ≥ 18 and yt-dlp.

python -m pip install -U yt-dlp
git clone https://github.com/pobibibi/youtube-transcript-mcp.git
cd youtube-transcript-mcp
npm install
npm run build

If yt-dlp is not on your PATH, set YTDLP_PATH to the executable. The server also falls back to python -m yt_dlp.

Keep yt-dlp current. It is the only component that talks to YouTube, and the only one that breaks when YouTube changes something.

Connect it

Claude Code

claude mcp add youtube-transcript --scope user -- node /absolute/path/to/youtube-transcript-mcp/dist/index.js

Claude Desktop — in claude_desktop_config.json:

{
  "mcpServers": {
    "youtube-transcript": {
      "command": "node",
      "args": ["/absolute/path/to/youtube-transcript-mcp/dist/index.js"],
      "env": {
        "TRANSCRIPTS_DIR": "/where/you/want/the/markdown"
      }
    }
  }
}

Any MCP client with stdio transport works the same way.

Use

Just ask:

Transcribe https://www.youtube.com/watch?v=aircAruvnKk

What does this video say about activation functions? https://youtu.be/aircAruvnKk

In the second case the model transcribes, reads the index, and opens only the section that answers you.

transcribe_video

Parameter

Type

Default

Description

url

string

—

Video URL or bare ID. youtube.com/watch, youtu.be and shorts all work.

language

string

the video's own

Caption language code: en, es, pt-BR…

file_name

string

video title

Output filename, without extension.

folder

string

TRANSCRIPTS_DIR or ./transcripts

Where to write the .md.

timestamps

boolean

true

Prefix each paragraph with [mm:ss].

include_description

boolean

true

Include the author's description.

block_seconds

number

300

Block size when the video has no chapters.

return_text

boolean

false

Also return the full Markdown. Expensive; rarely what you want.

list_languages

Reports the video's own language, its duration, its chapter count, and every caption track it carries. Useful before transcribing when you are not sure the language you want exists.

How it works

URL
 │
 ├─ yt-dlp --dump-single-json ──────► metadata: title, chapters, caption tracks
 │
 ├─ pickTrack() ───────────────────► which language, manual or automatic
 │
 ├─ yt-dlp --write-subs --sub-format json3
 │        └─ parseJson3() ─────────► cues, rollup duplicates removed
 │
 ├─ buildMarkdown()
 │        ├─ sections from chapters, or fixed time blocks
 │        └─ paragraphs, clipped to section boundaries
 │
 └─ write .md ─────────────────────► return path + summary

Four modules, each with one job: ytdlp.ts talks to YouTube, subtitles.ts parses caption formats, markdown.ts shapes the document, transcribe.ts orchestrates. index.ts is only the MCP surface.

Three decisions worth explaining

json3 over VTT. YouTube's automatic captions emit every line twice — once as a "rollup" fragment, once complete. In VTT you have to guess which is which; in json3 the duplicate carries an aAppend flag and can be dropped exactly. VTT parsing stays as a fallback for the handful of manual tracks yt-dlp cannot hand over as json3.

No language guessing. YouTube will machine-translate its machine transcription into ~150 languages on request. Stacking those two produces text the speaker never said. Without an explicit language, the server stays on the video's own language and prefers human-written captions when they exist.

Paragraphs never cross a chapter boundary. Paragraphs are built within each section, not sliced afterwards. Cutting the other way around files a chapter's opening sentences under the previous chapter and leaves the chapter itself looking empty — which is exactly wrong for a document meant to be read one section at a time.

Limitations

  • No captions, no transcript. This reads subtitles; it does not transcribe audio. Videos with automatic captions disabled cannot be processed.

  • Automatic captions are rough. Unreliable punctuation, mangled proper nouns and technical terms. The generated file says so in its own header.

  • Live streams must finish first.

  • HTTP 429. YouTube rate-limits bursts. The server backs off once and then explains what to do; browser cookies via YTDLP_COOKIES_FROM_BROWSER usually settle it.

Environment variables

Variable

Purpose

TRANSCRIPTS_DIR

Default output folder.

YTDLP_PATH

Path to the yt-dlp executable.

YTDLP_COOKIES_FROM_BROWSER

Browser to pull cookies from (chrome, firefox…). Needed for age-restricted videos.

YTDLP_COOKIES_FILE

Same, from a cookies.txt file.

YTDLP_PROXY

Proxy for all requests.

Development

npm test                                       # 21 offline unit tests
npm run dev                                    # hot reload
npm run smoke                                  # end-to-end over stdio, hits the network
node test/smoke.mjs "https://youtu.be/VIDEO_ID"
python assets/make_demo.py                     # regenerate the demo GIF

The unit tests are deliberately offline — parsing, paragraphing and track selection are pure functions, so CI never depends on YouTube being reachable. npm run smoke starts the compiled server and speaks JSON-RPC to it, exactly as a client does.

Notice

This downloads publicly available subtitles, the same way yt-dlp does. Use it for notes, study and research, respecting YouTube's terms of service and the rights of the video's author. Generating a transcript does not make it yours.

License

MIT © pobibibi

Available Tools

2 tools
list_languagesA

Show which captions a YouTube video has (manual and automatic), its own language, its duration and how many chapters it carries. Useful before transcribing when you are unsure the language you want exists.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYesYouTube video URL or bare video ID.

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden. It conveys read-only behavior ('Show') and explicitly says it is not for transcribing. However, it does not discuss edge cases or limitations, so transparency is only basic.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with zero fluff. The first sentence delivers the main purpose, and the second gives a practical usage tip, making every word earn its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter tool with no output schema, the description lists the expected output components (captions, language, duration, chapters), giving sufficient context without needing deeper details.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single parameter url is fully described in the schema as 'YouTube video URL or bare video ID.' The description adds no extra parameter detail, so baseline 3 applies due to high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states a specific verb ('Show') and resource ('which captions a YouTube video has'), listing the exact metadata returned. Distinguishes itself from the sibling transcribe_video by positioning itself as a pre-transcription check.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear context: use before transcribing when unsure if the desired language exists. It does not explicitly state when not to use or name alternatives, but the guidance is unambiguous.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

transcribe_videoA

Transcribe a YouTube video and save it as a Markdown file built for an LLM to read: front matter with the video's facts, a linked chapter index, and the text in paragraphs with timestamps. By default it does NOT return the transcript, only the file path and a summary (title, channel, duration, word count and section list), so you can then read the whole file or just the section you need. Uses the video's own language unless another one is requested.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYesYouTube video URL (youtube.com/watch?v=..., youtu.be/..., shorts) or bare video ID.
folderNoWhere to save the .md. Defaults to the TRANSCRIPTS_DIR environment variable, or ./transcripts.
languageNoCaption language code, e.g. 'en' or 'es'. Defaults to the video's own language. Requesting a language the video has no manual captions for returns YouTube's machine translation of its machine transcription, which is noticeably less reliable.
file_nameNoName of the .md file, without extension. Defaults to the video title.
timestampsNoPrefix each paragraph with [mm:ss]. Default true.
return_textNoAlso return the full Markdown in the response. Default false: it costs a lot of tokens and reading the file afterwards, whole or in parts, is almost always better.
block_secondsNoWhen the video has no chapters, split the transcript into blocks of this many seconds. Default 300.
include_descriptionNoInclude the description written by the video's author. Default true.

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden, and it excels: it discloses that the transcript is not returned by default, that a file is saved, the summary structure, the language fallback behavior, and the reliability caveat for machine translations. This is thorough and prevents false expectations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single dense paragraph but remains readable and every sentence earns its place. It could be slightly more structured with bullets to improve scannability, but it is not unnecessarily verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex tool with 8 parameters, a file-saving side effect, and no output schema, the description covers the default return value, summary fields, file path resolution, language handling, timestamps, chapter behavior, and description toggles. No critical gaps are apparent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but the description adds substantial meaning: it explains the machine-translation caveat for language, the token cost of return_text, the block_seconds behavior in the absence of chapters, and the default folder resolution. These insights are not evident from the schema alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb "Transcribe" and the resource (YouTube video), and specifies the output format: an LLM-ready Markdown file with front matter, chapter index, and timestamped paragraphs. It distinguishes itself from the sibling tool list_languages, which is about language codes, not transcription.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit usage context: it explains the default behavior (does not return transcript, saves file path and summary), how to request a language, and the trade-offs of return_text. It doesn't explicitly name list_languages as a prerequisite, but the language-code context implies its use, and the guidance on when to avoid machine translation is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 2 tool updatesv1.0.0
    • First observedlist_languages
    • First observedtranscribe_video
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.2/5.0

Scored across 2 tools

Disambiguation5/5

The two tools have clearly distinct purposes: transcribe_video retrieves and saves a transcript, while list_languages provides metadata about available captions. No overlap or ambiguity exists.

Naming Consistency5/5

Both tools follow a consistent verb_noun pattern: transcribe_video and list_languages. The naming is clear, predictable, and uniform.

Tool Count3/5

With only two tools, the server feels slightly thin even for its narrow domain. However, the two tools cover the core workflow of checking languages and transcribing, so the count is borderline but defensible.

Completeness4/5

The server covers the essential transcript retrieval cycle well. A minor gap is that transcribe_video does not return the transcript directly, requiring a follow-up file read, but the workflow is complete and workable.

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/pobibibi/youtube-transcript-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server