Skip to main content
Glama
yunlinwu

youtube-transcript-mcp

by yunlinwu
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

YouTube Transcript MCP Server

An MCP server that gives Claude access to YouTube video transcripts. Extract full transcripts, search for keywords with timestamps, and get direct YouTube links to matching moments.

Tools

get_transcript

Extract the full timestamped transcript from any YouTube video.

Title: Rick Astley - Never Gonna Give You Up (Official Video)
Channel: Rick Astley
Duration: 3:33
Source: captions | Language: en | Segments: 60
---
[0:01] [♪♪♪]
[0:18] ♪ We're no strangers to love ♪
[0:22] ♪ You know the rules and so do I ♪
...

search_transcript

Keyword search across a video's transcript. Matches are grouped, marked with >>>, and include a YouTube link to jump to that moment.

Search: "give you up" in Rick Astley - Never Gonna Give You Up
Matches: 9 hits in 2 group(s)

--- Group 1 (1 hit(s)) — https://www.youtube.com/watch?v=dQw4w9WgXcQ&t=43 ---
     [0:40] ♪ Gotta make you understand ♪
 >>> [0:43] ♪ Never gonna give you up ♪
     [0:45] ♪ Never gonna let you down ♪

Related MCP server: YouTube Ultimate Toolkit MCP

Install

git clone https://github.com/yunlinwu/youtube-transcript-mcp.git
cd youtube-transcript-mcp
pip install -e .

For Whisper fallback (transcribes videos without captions):

pip install -e ".[whisper]"

Setup

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

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

Claude Code

Add to .claude/settings.json:

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

Then restart Claude Desktop or Claude Code to pick up the server.

How it works

  1. You ask Claude about a YouTube video

  2. Claude calls get_transcript or search_transcript via MCP

  3. The server uses yt-dlp to fetch captions (or Whisper to transcribe audio as a fallback)

  4. Claude gets back a compact, readable transcript and can summarize, search, or analyze it

Requirements

  • Python 3.10+

  • yt-dlp (installed automatically)

  • FFmpeg (only needed for Whisper fallback)

Development

python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest

License

MIT

Available Tools

2 tools
get_transcript_toolA

Get the full transcript of a YouTube video with timestamps.

Args: url: YouTube video URL or video ID lang: Language code for captions (default: "en") use_whisper_fallback: If True, use Whisper when captions unavailable

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYes
langNoen
use_whisper_fallbackNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.5/5.0
Behavior3/5

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

The description discloses key behavior: obtaining transcript with timestamps and optional Whisper fallback. However, it omits details about authentication, rate limits, or error handling when captions are unavailable (e.g., falls back to Whisper only if flag is true). With no annotations, the description could be more explicit about edge cases.

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?

The description is exceptionally concise with no redundant information. The main purpose is stated upfront, followed by a clear parameters list. Every sentence serves a purpose.

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?

Given the presence of an output schema (which likely documents return format), the description covers the essential inputs and fallback behavior. It could mention that the result includes timestamps inline, but overall it is sufficiently complete for a simple retrieval tool.

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?

The description compensates for zero schema coverage by explaining each parameter's purpose, defaults, and usage. For example, 'url' is described as 'YouTube video URL or video ID', and the fallback parameter's behavior is clarified. Adding example values could improve it further.

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?

The description clearly states the tool retrieves the full transcript with timestamps from YouTube. While it distinguishes itself from the sibling 'search_transcript' by focusing on full retrieval, it does not explicitly differentiate use cases.

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

Usage Guidelines2/5

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

No guidance is provided on when to use this tool versus the sibling 'search_transcript'. The description only explains parameters but lacks context for tool selection.

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

search_transcriptB

Search a YouTube video's transcript for matching segments.

Args: url: YouTube video URL or video ID query: Search term to find in the transcript lang: Language code for captions (default: "en") context_seconds: Seconds of context around each match (default: 30)

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYes
langNoen
queryYes
context_secondsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.1/5.0
Behavior2/5

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

With no annotations, the description carries full burden for behavioral disclosure. It mentions context_seconds but omits details about output format, timestamps, rate limits, or authentication needs. The minimal description leaves significant behavioral gaps.

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?

The description is very concise: one sentence summary followed by a bulleted list of arguments. Every sentence adds value with no redundancy. Structure is clear and scannable.

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

Completeness3/5

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

Given the tool has 4 parameters, no annotations, and an output schema exists, the description covers basic requirements. However, it does not address error conditions, prerequisites (e.g., video must have captions), or the structure of returned segments, leaving some gaps.

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?

Schema coverage is 0%, so the description must compensate. It provides brief explanations for all four parameters (url, query, lang, context_seconds) that add meaning beyond property names, but the explanations are minimal and lack format constraints or examples.

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?

The description clearly states the tool searches a YouTube video's transcript for matching segments, using specific verb and resource. It distinguishes from the sibling get_transcript_tool by implication (search vs. full retrieval), but does not explicitly contrast them.

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

Usage Guidelines2/5

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

No guidance is provided on when to use this tool versus the sibling get_transcript_tool or any alternatives. The description simply states what it does without usage context.

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.

  1. 2 tool updatesv0.1.0
    • First observedget_transcript_tool
    • First observedsearch_transcript
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.5/5.0

Scored across 2 tools

Disambiguation5/5

Each tool has a clear, distinct purpose: one fetches the full transcript, the other searches within it. No functional overlap.

Naming Consistency3/5

Both use snake_case but the naming pattern is inconsistent: 'get_transcript_tool' includes a redundant '_tool' suffix while 'search_transcript' does not.

Tool Count5/5

Two tools are well-scoped for the server's focused purpose of YouTube transcript access and search. No unnecessary tools.

Completeness4/5

The tool surface covers the core operations (full transcript retrieval and search) but lacks auxiliary features like language detection or transcript availability checking.

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • YouTube MCP Server

    Nocodeboy
    A
    license
    Not graded
    quality
    D
    maintenance
    An MCP server that allows Claude and other AI assistants to interact with the YouTube API, providing tools to search videos/channels and retrieve detailed information about them.
    17 npm
    1
    MIT

  • YouTube Ultimate Toolkit MCP

    Comzee
    A
    license
    A
    quality
    C
    maintenance
    A comprehensive MCP server that provides Claude AI with full access to YouTube content, including searchable transcripts, metadata, comments, and playlists. It uniquely supports capturing video screenshots and extracting audio clips for analysis across both local and remote platforms.
    5
    13 npm
    3
    MIT

  • tldw-mcp

    limace11
    A
    license
    Not graded
    quality
    D
    maintenance
    MCP server that extracts YouTube video transcripts (including metadata) as Markdown, enabling AI to summarize and discuss video content without watching it.
    MIT