The YouTube Transcript MCP Server lets you fetch, search, and analyze YouTube video transcripts using yt-dlp for reliable, rate-limit-bypassing extraction.
Fetch Transcripts (get_transcript): Retrieve full or time-filtered transcripts by video ID or URL, with optional language selection and timestamp preservation.
Search Transcripts (search_transcript): Find specific text within transcripts with configurable context windows and case-sensitive/insensitive matching.
List Available Languages (get_available_languages): Discover all available transcript languages (manual and auto-generated) for any video — 100+ languages supported.
Transcript Analytics (get_transcript_summary): Get advanced insights including speaking pace, filler word detection, engagement metrics (questions/exclamations), top frequent words, content tone indicators, and reading time estimates.
Prompt Templates: Pre-built prompts for summarizing a video (summarize_video) or searching for a topic within a video (search_topic_in_video).
Universal input support: Accepts both video IDs and full YouTube URLs; time parameters support integers, floats, strings, or nulls.
Reliability features: Transcript caching (10-min TTL), automatic retries with backoff, and robust extraction via yt-dlp.
Flexible deployment: STDIO and HTTP transport modes, plus Docker support with multi-arch images (amd64/arm64) and health checks.
Provides tools for fetching YouTube video transcripts, searching transcript content, checking available languages, and extracting transcript summaries with timestamp filtering capabilities
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@YouTube Transcript MCP Server get the transcript for https://youtu.be/jNQXAC9IVRw"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A production-ready Model Context Protocol (MCP) server that provides YouTube transcript fetching capabilities using yt-dlp CLI for reliable subtitle extraction. Bypasses YouTube's rate limiting through CLI-based implementation.
CLI-Based: Uses yt-dlp subprocess to avoid HTTP rate limiting
FastMCP 2.14.5: Tool annotations, context logging, progress reporting, prompt templates
GHCR CI/CD: Multi-arch Docker images (amd64/arm64) built on every push
Universal Compatibility: Time parameters work across all MCP clients
Advanced Analytics: Enhanced transcript summary with content analysis
Multi-Language: 100+ languages with auto-generated and manual transcripts
Related MCP server: YouTube Transcript MCP Server
Fetch transcripts from YouTube videos with metadata and timestamps
Time filtering - extract specific segments by start/end times
Search functionality - find text within transcripts with context
Advanced analytics - speaking pace, filler words, engagement metrics, top words
Language detection - list available transcript languages
Prompt templates - pre-built prompts for video summarization and topic search
Transcript caching - 10-minute TTL cache avoids redundant YouTube requests
Retry with backoff - automatic retries on timeouts and transient errors
Universal format support - handles both video IDs and full YouTube URLs
Dual transport - STDIO and HTTP transport modes
Docker support - containerized deployment via GHCR with health checks
# Pull from GHCR and run
docker run -d -p 8080:8080 ghcr.io/suckerfish/yttranscript_mcp:latest
# Or use docker compose
docker compose up -d
# Health check
curl http://localhost:8080/health# Install dependencies
uv pip install -e .
# Run server (STDIO mode)
python src/server.py
# Run server (HTTP mode)
uvicorn src.server:app --host 0.0.0.0 --port 8080All tools are read-only (readOnlyHint=True) and tagged read.
get_transcript - Fetch video transcripts with optional time filtering
search_transcript - Search for specific text within transcripts
get_transcript_summary - Advanced analytics and content insights
get_available_languages - List available transcript languages
summarize_video(video_id, language_code) - Summarize a YouTube video transcript
search_topic_in_video(video_id, topic) - Search for and analyze a topic within a video
# Discover tools
mcp tools .venv/bin/python src/server.py
# Basic transcript
mcp call get_transcript --params '{"video_id":"jNQXAC9IVRw"}' .venv/bin/python src/server.py
# Time-filtered transcript
mcp call get_transcript --params '{"video_id":"jNQXAC9IVRw", "start_time": 10, "end_time": 60}' .venv/bin/python src/server.py
# Search within transcript
mcp call search_transcript --params '{"video_id":"jNQXAC9IVRw", "query":"example"}' .venv/bin/python src/server.py
# Advanced analytics
mcp call get_transcript_summary --params '{"video_id":"jNQXAC9IVRw"}' .venv/bin/python src/server.py
# Available languages
mcp call get_available_languages --params '{"video_id":"jNQXAC9IVRw"}' .venv/bin/python src/server.py{
"yttranscript": {
"url": "http://localhost:8080/mcp"
}
}{
"yttranscript": {
"command": "uv",
"args": [
"run",
"--directory", "/path/to/yttranscript_mcp",
"src/server.py"
]
}
}Time filtering parameters accept multiple formats:
Integers: {"start_time": 10}
Floats: {"start_time": 10.5}
Strings: {"start_time": "10"}
Nulls: {"start_time": null} or {"start_time": "null"}
The get_transcript_summary tool provides:
Speaking pace analysis (words per minute with descriptive labels)
Filler word detection (um, uh, like, etc.) with percentages
Content indicators (conversational, formal, high energy)
Top frequent words (excluding stop words)
Engagement metrics (questions, exclamations)
Reading time estimates at multiple speeds
No rate limiting - bypasses YouTube's HTTP restrictions
Reliable extraction - uses yt-dlp's robust parsing
Automatic retries - backoff on timeouts and transient errors
Format flexibility - handles VTT, JSON3, and other subtitle formats
YT_TRANSCRIPT_SERVER_PORT=8080 # Server port (default: 8080)
YT_TRANSCRIPT_SERVER_HOST=0.0.0.0 # Server host (default: 0.0.0.0)
YT_TRANSCRIPT_DEBUG=false # Debug modefastmcp>=2.14.5,<3.0.0 - MCP server framework
yt-dlp - YouTube transcript extraction via CLI
pydantic>=2.0.0 - Data validation and models
uvicorn>=0.24.0 - ASGI server for HTTP transport
This project uses uv for package management.
Docker images are built by GitHub Actions on every push to main and published to GHCR:
ghcr.io/suckerfish/yttranscript_mcp:latestMulti-arch support: linux/amd64 and linux/arm64.
Tool not found: Verify @mcp.tool() decorator in tool definitions
Validation errors: Video IDs must be 11 characters, time values must be non-negative
Time filtering issues: Parameters accept multiple formats (int/float/string/null)
Transport issues: Use uvicorn for HTTP mode, python src/server.py for STDIO
No transcript available: Check with get_available_languages first
Missing session ID: Server uses stateless_http=True for clients without session management
This project is open source and available under the MIT License.
Get list of available transcript languages for a YouTube video using yt-dlp.
Args:
video_id: YouTube video ID or URL
Returns:
List of available languages with metadata
| Name | Required | Description | Default |
|---|---|---|---|
| video_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool retrieves a list with metadata, but doesn't describe key behaviors such as error handling (e.g., for invalid video IDs), rate limits, authentication needs, or performance characteristics. This leaves significant gaps for an AI agent to understand how the tool operates in practice.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and appropriately sized, with a clear purpose statement followed by Args and Returns sections. Each sentence earns its place by defining the tool's function and parameters. It could be slightly more concise by integrating the parameter explanation into the main text, but overall it's efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (a tool interfacing with external services like YouTube and yt-dlp), lack of annotations, and no output schema, the description is incomplete. It doesn't explain the return value structure (e.g., what metadata fields are included), error conditions, or dependencies. This makes it inadequate for an AI agent to fully understand the tool's behavior and outputs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds basic semantics for the single parameter: 'video_id: YouTube video ID or URL.' This clarifies that the input can be either an ID or a full URL, which is useful since the schema has 0% description coverage and only provides a generic title. However, it doesn't elaborate on format constraints (e.g., URL patterns, ID length) or examples, so it only partially compensates for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get list of available transcript languages for a YouTube video using yt-dlp.' It specifies the verb ('Get'), resource ('available transcript languages'), and technology context ('using yt-dlp'), making the function unambiguous. However, it doesn't explicitly differentiate from sibling tools like get_transcript or search_transcript, which prevents a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like get_transcript (which might fetch transcripts) or search_transcript (which might search within transcripts), nor does it specify prerequisites or exclusions. The only implied usage is for obtaining language metadata, but this is too vague for effective tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the transcript for a YouTube video using yt-dlp.
Args:
video_id: YouTube video ID or URL
language_code: Optional language code (e.g., 'en', 'es'). If not provided, uses auto-detected language.
preserve_formatting: Whether to preserve timestamp formatting in plain text
start_time: Optional start time in seconds to filter transcript
end_time: Optional end time in seconds to filter transcript
Returns:
Complete transcript data with metadata
| Name | Required | Description | Default |
|---|---|---|---|
| video_id | Yes | ||
| language_code | No | ||
| preserve_formatting | No | ||
| start_time | No | ||
| end_time | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses key behavioral traits: it fetches transcripts (implying read-only, non-destructive), uses yt-dlp (implementation detail), and returns 'Complete transcript data with metadata'. However, it lacks details on error handling, rate limits, authentication needs, or what 'metadata' includes, leaving gaps for a tool with 5 parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and appropriately sized. It front-loads the core purpose in the first sentence, followed by a clear 'Args' and 'Returns' section with bullet-like formatting. Every sentence adds value without redundancy, making it easy to scan and understand.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters, no annotations, and no output schema, the description does a strong job covering inputs and basic behavior. However, it lacks details on output structure (beyond 'metadata'), error cases, or performance aspects, which could be important for a tool fetching external data. It's mostly complete but has minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate fully. It adds significant meaning beyond the schema by explaining each parameter's purpose and usage: video_id accepts 'ID or URL', language_code uses 'auto-detected' as default, preserve_formatting affects 'timestamp formatting in plain text', and start_time/end_time 'filter transcript'. This effectively documents all 5 parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Fetch the transcript') and resource ('for a YouTube video'), using the implementation detail 'using yt-dlp' for additional context. It distinguishes itself from siblings like get_available_languages (lists languages), get_transcript_summary (summarizes), and search_transcript (searches within transcripts).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage through parameter descriptions (e.g., 'Optional language code', 'Optional start time'), suggesting when to use certain features, but lacks explicit guidance on when to choose this tool over alternatives like get_transcript_summary or search_transcript. No clear exclusions or prerequisites are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a summary of the transcript including key statistics and sample text.
Args:
video_id: YouTube video ID or URL
language_code: Optional language code
max_length: Maximum length of sample text
Returns:
Summary with statistics and sample text
| Name | Required | Description | Default |
|---|---|---|---|
| video_id | Yes | ||
| language_code | No | ||
| max_length | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It mentions that the tool returns a summary with statistics and sample text, which gives some output context, but it lacks details on permissions, rate limits, error handling, or whether it's a read-only operation. For a tool with no annotations, this is insufficient to ensure safe and effective use.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and concise, with no wasted words. It front-loads the purpose in the first sentence, followed by clear sections for arguments and returns. Each sentence adds value, making it easy to parse and understand quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (3 parameters, no output schema, no annotations), the description is partially complete. It covers the purpose and parameters adequately but lacks usage guidelines, behavioral details, and output specifics. Without annotations or an output schema, more context on the return format or operational constraints would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaningful semantics beyond the input schema, which has 0% description coverage. It explains that 'video_id' can be a YouTube video ID or URL, 'language_code' is optional, and 'max_length' controls the sample text length. This compensates well for the schema's lack of descriptions, though it doesn't specify format details like valid language codes or length constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get a summary of the transcript including key statistics and sample text.' It specifies the verb ('Get') and resource ('transcript summary'), making the function unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'get_transcript' or 'search_transcript', which likely provide different outputs or functionalities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools such as 'get_transcript' or 'search_transcript', nor does it specify use cases, prerequisites, or exclusions. This leaves the agent without 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 for specific text within a YouTube video transcript.
Args:
video_id: YouTube video ID or URL
query: Text to search for
language_code: Optional language code for transcript
case_sensitive: Whether search should be case sensitive
context_window: Seconds of context to include before/after matches
Returns:
Search results with context and timestamps
| Name | Required | Description | Default |
|---|---|---|---|
| video_id | Yes | ||
| query | Yes | ||
| language_code | No | ||
| case_sensitive | No | ||
| context_window | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It describes what the tool does (search transcripts) and mentions the return format (results with context and timestamps), but doesn't disclose important behavioral traits like error conditions, rate limits, authentication requirements, or what happens with invalid inputs. The description provides basic functional context but lacks operational details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly structured and concise with zero wasted words. It begins with a clear purpose statement, then provides organized parameter explanations in an Args section, and concludes with return value information. Every sentence serves a specific purpose, and the information is front-loaded with the most important details first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters with no schema descriptions and no output schema, the description provides adequate parameter semantics but lacks completeness about behavioral aspects. For a search tool with multiple configuration options and no annotations, the description should ideally mention more about error handling, result format details, or limitations. It covers the basics but leaves gaps in operational context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates well by explaining all 5 parameters in the Args section, adding meaningful context beyond just parameter names. It clarifies that video_id accepts 'YouTube video ID or URL', query is 'Text to search for', language_code is 'Optional language code for transcript', case_sensitive controls 'Whether search should be case sensitive', and context_window specifies 'Seconds of context to include before/after matches'. This provides good semantic understanding of each parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verb ('search') and resource ('YouTube video transcript'), distinguishing it from sibling tools like get_transcript (which retrieves full transcripts) and get_transcript_summary (which provides summaries). The description explicitly mentions searching for specific text within transcripts, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by specifying it searches within YouTube video transcripts, but doesn't explicitly state when to use this tool versus alternatives like get_transcript (for full transcripts) or get_available_languages (for language options). No guidance is provided about prerequisites, limitations, or when-not-to-use scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.0get_available_languagesget_transcriptget_transcript_summarysearch_transcriptEach tool has a clearly distinct purpose with no overlap: get_available_languages lists languages, get_transcript fetches full transcripts, get_transcript_summary provides statistical summaries, and search_transcript performs text searches. The descriptions reinforce these distinct roles, making tool selection unambiguous for an agent.
All tool names follow a consistent verb_noun pattern with snake_case (e.g., get_available_languages, get_transcript, get_transcript_summary, search_transcript). The naming is predictable and readable throughout the set, with no deviations in style or convention.
With 4 tools, the server is well-scoped for its purpose of YouTube transcript retrieval and analysis. Each tool earns its place by covering distinct aspects of the workflow (language discovery, full transcript fetching, summarization, and searching), avoiding bloat while providing complete functionality.
The tool set offers complete coverage for the domain of YouTube transcript operations. It includes language discovery, full transcript retrieval, summarization, and searching, with no obvious gaps. Agents can perform all core transcript-related tasks without dead ends or missing operations.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Search YouTube, read video metadata, and fetch transcripts with language preferences
Extract YouTube transcripts, search what was said, and read on-screen frames with cited timestamps.
YouTube transcripts, search, channels, playlists and bulk transcript jobs for AI agents. 14 tools.
Fetch transcripts, subtitles, chapters, metadata and frames from YouTube and 10+ video platforms
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/suckerfish/yttranscript_mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server