YouTube MCP Server

Youtube Get Transcript

youtube_get_transcript

Fetch a YouTube video's transcript as plain text, optionally translated.

Instructions

Fetch a YouTube video's transcript as plain text, optionally translated.

Returns the caption text for one 11-character video ID, with the language that was actually used, whether it is auto-generated, and next_cursor.

Timestamps are OFF by default because each [mm:ss] marker costs tokens; when include_timestamps is true a marker is inserted wherever the caption minute changes (a word-level auto-generated track gets far fewer markers than segments).

translate_to asks YouTube to translate the caption track that languages selects into that language code, so a caller can read a video that has no captions of its own language. Get valid targets from youtube_list_transcript_languages (translatable_to). The text returned is YouTube's machine translation, not the creator's words: it is not a translation this server performed, and it can be wrong. is_translated is true when the text differs in language from the track it came from, translated_from carries that track's language code, and is_generated is always true for a translation because YouTube's translation is machine output. Paging, truncation and the cursor contract are the same as for an untranslated transcript.

Long transcripts are truncated at the server's RESPONSE_LIMIT and cut on caption boundaries: read next_cursor and call again with it to get the following page — next_cursor: null (and truncated: false) means you have the whole thing. Each page repeats the time anchor of its first segment.

Costs no YouTube Data API quota: transcripts are scraped from YouTube's internal caption endpoint, not the Data API, and translation is a parameter on that same endpoint. They are cached forever, so a repeat call is free — translated pages under their own cache key, never mixed with the untranslated ones. Failures are expected and specific — captions may be disabled, absent in the requested languages, or the IP may be blocked (transient). A language the video cannot be translated into is an INVALID_REQUEST error: check the listing, do not retry. Age-restricted videos cannot be read.

Input Schema

Name	Required	Description	Default
`cursor`	No
`video_id`	Yes
`languages`	No
`translate_to`	No
`include_timestamps`	No

Output Schema

Name	Required	Description	Default
`text`	Yes
`language`	Yes
`video_id`	Yes
`truncated`	Yes
`next_cursor`	Yes
`is_generated`	Yes
`is_translated`	No
`language_code`	Yes
`translated_from`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedv0.4.0Oct 21, 2026

addedInput schema / properties / translate_to

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null
+}

changedOutput schema / description

Previous value: -"A slice of a transcript as plain text."New value: +"A slice of a transcript as plain text.\n\n`is_translated` / `translated_from` record provenance: when set, the text is YouTube's\ntranslation of the `translated_from` track, not the creator's words."

addedOutput schema / properties / is_translated

Added value: +{
+  "default": false,
+  "type": "boolean"
+}

addedOutput schema / properties / translated_from

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null
+}

First observedv0.1.0Oct 4, 2026

TDQS

A4.3/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 does: no Data API quota cost, forever-caching with separate keys for translated pages, truncation at `RESPONSE_LIMIT` on caption boundaries, and a specific failure taxonomy (captions disabled, absent language, transient IP block, INVALID_REQUEST, age-restricted). It also warns the returned text is YouTube's machine translation and may be wrong.

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?

Front-loaded with the core action, then organized into translation, paging, and cost/failure blocks — each paragraph has a job. It runs long, and the `is_translated`/`translated_from`/`is_generated` explanation partly restates return fields that an output schema already covers.

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 5-parameter scraping tool with no annotations and an output schema, this covers the paging loop, truncation anchor, cache behavior, quota impact, and error handling. An agent has everything needed to call it correctly and interpret a failed call.

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

Parameters4/5

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

Schema coverage is 0%, so the description must compensate and largely does: `video_id` is one 11-character ID, `cursor` is what you pass back from `next_cursor`, `include_timestamps` trades tokens for `[mm:ss]` markers, and `translate_to` targets the track selected by `languages`. What remains implicit is how `languages` is resolved when several are supplied (preference order vs. first available).

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

Purpose4/5

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

Opens with a specific verb and resource: "Fetch a YouTube video's transcript as plain text, optionally translated," scoped to a single 11-character video ID. It differentiates on timestamps (off by default) but never names the obvious sibling `youtube_get_timestamped_transcript`, leaving the agent to infer the split.

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?

Gives concrete operating instructions: get valid `translate_to` targets from `youtube_list_transcript_languages`, page with `next_cursor` until it is null, and do not retry an `INVALID_REQUEST` language error. It stops short of stating when to prefer this over the timestamped-transcript sibling.

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

Deploy Server