Extracts transcripts from YouTube videos with support for timestamps, metadata, and file exports.
Click on "Deploy 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 extract transcript from https://youtu.be/dQw4w9WgXcQ"
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 Model Context Protocol (MCP) server that enables Large Language Models (LLMs) to extract transcripts from YouTube videos. Built with the reliable youtubei.js library, this server provides seamless transcript extraction with support for timestamps, metadata, and file exports.
🎥 Extract transcripts from any YouTube video with captions
⏱️ Timestamp support - Get transcripts with or without timestamps
📊 Rich metadata - Word count, duration, segment count, and more
💾 Export to files - Save transcripts as text files
🔧 Flexible input - Accepts full URLs, short URLs, or just video IDs
⚡ High reliability - Uses YouTube's internal API via youtubei.js
🚀 No API key required - Works out of the box
🛡️ Error handling - Clear, actionable error messages
Related MCP server: YouTube Insights MCP Server
# Clone the repository
git clone https://github.com/tanush-yadav/youtube-transcript-mcp.git
cd youtube-transcript-mcp
# Install dependencies
npm installnpm install @tanush-yadav/youtube-transcript-mcpOr using yarn:
yarn add @tanush-yadav/youtube-transcript-mcpAdd the server to your Claude Desktop configuration:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json
{
"mcpServers": {
"youtube-transcript": {
"command": "node",
"args": ["/absolute/path/to/youtube-transcript-mcp/index.js"]
}
}
}Or if installed globally via npm:
{
"mcpServers": {
"youtube-transcript": {
"command": "npx",
"args": ["@tanush-yadav/youtube-transcript-mcp"]
}
}
}get_transcriptExtract transcript from a YouTube video with optional timestamps.
Parameters:
url (string, required): YouTube video URL or video ID
include_timestamps (boolean, optional): Include timestamps in output (default: false)
Example Request:
{
"name": "get_transcript",
"arguments": {
"url": "https://youtube.com/watch?v=dQw4w9WgXcQ",
"include_timestamps": true
}
}Example Output with timestamps:
[00:00] We're no strangers to love
[00:04] You know the rules and so do I
[00:08] A full commitment's what I'm thinking ofget_transcript_with_metadataExtract transcript along with comprehensive metadata.
Parameters:
url (string, required): YouTube video URL or video ID
Example Response:
{
"metadata": {
"video_id": "dQw4w9WgXcQ",
"video_url": "https://youtube.com/watch?v=dQw4w9WgXcQ",
"word_count": 251,
"segment_count": 42,
"duration": "3:32",
"duration_seconds": 212,
"language": "en",
"is_auto_generated": false
},
"transcript": "Never gonna give you up...",
"full_transcript_length": 1234
}save_transcriptSave transcript to text file(s) on the local filesystem.
Parameters:
url (string, required): YouTube video URL or video ID
filename (string, required): Base filename (without extension)
with_timestamps (boolean, optional): Save version with timestamps (default: true)
Example:
{
"name": "save_transcript",
"arguments": {
"url": "https://youtu.be/dQw4w9WgXcQ",
"filename": "rickroll_transcript",
"with_timestamps": true
}
}Creates files:
rickroll_transcript_clean.txt - Plain text transcript
rickroll_transcript_with_timestamps.txt - Transcript with timestamps (if enabled)
import { Client } from '@modelcontextprotocol/sdk/client/index.js'
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'
// Initialize transport
const transport = new StdioClientTransport({
command: 'node',
args: ['/path/to/youtube-transcript-mcp/index.js'],
})
// Create client
const client = new Client({
name: 'youtube-transcript-client',
version: '1.0.0',
})
// Connect and use
await client.connect(transport)
// Get transcript with timestamps
const result = await client.callTool({
name: 'get_transcript',
arguments: {
url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
include_timestamps: true,
},
})
console.log(result.content[0].text)// Coming soon: Direct module import support
import { YouTubeTranscriptExtractor } from '@tanush-yadav/youtube-transcript-mcp'
const extractor = new YouTubeTranscriptExtractor()
const transcript = await extractor.getTranscript('dQw4w9WgXcQ')
console.log(transcript)The server accepts various YouTube URL formats:
✅ Standard: https://www.youtube.com/watch?v=VIDEO_ID
✅ Short: https://youtu.be/VIDEO_ID
✅ Embed: https://www.youtube.com/embed/VIDEO_ID
✅ Mobile: https://m.youtube.com/watch?v=VIDEO_ID
✅ Shorts: https://www.youtube.com/shorts/VIDEO_ID
✅ With timestamps: https://youtube.com/watch?v=VIDEO_ID&t=123
✅ With playlist: https://youtube.com/watch?v=VIDEO_ID&list=PLAYLIST_ID
✅ Just video ID: dQw4w9WgXcQ
Once configured, you can ask Claude:
"Get the transcript from https://www.youtube.com/watch?v=dQw4w9WgXcQ"
"Extract the YouTube transcript with timestamps from video ID abc123"
"Save the transcript from this video to a file: [URL]"
"Get detailed metadata and transcript from: [URL]"
"Summarize this YouTube video: [URL]" (Claude will fetch and summarize)npm testgit clone https://github.com/tanush-yadav/youtube-transcript-mcp.git
cd youtube-transcript-mcp
npm install
npm run buildnpm run devCreate a test file test-client.js:
import { Client } from '@modelcontextprotocol/sdk/client/index.js'
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'
const transport = new StdioClientTransport({
command: 'node',
args: ['./index.js'],
})
const client = new Client({
name: 'test-client',
version: '1.0.0',
})
await client.connect(transport)
// List available tools
const tools = await client.listTools()
console.log('Available tools:', tools)
// Test transcript extraction
const result = await client.callTool({
name: 'get_transcript',
arguments: {
url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
},
})
console.log('Transcript:', result.content[0].text)
await transport.close()"No transcript available"
✓ Ensure the video has captions/subtitles available
✓ Check if the video is public and not age-restricted
✓ Some live streams may not have transcripts available
Connection errors
✓ Verify your internet connection
✓ Check if YouTube is accessible in your region
✓ Ensure Node.js version is 18.0 or higher
MCP server not found in Claude
✓ Verify the path in your Claude configuration is absolute
✓ Ensure Node.js is properly installed and in PATH
✓ Restart Claude Desktop after configuration changes
Permission errors when saving files
✓ Ensure write permissions in the target directory
✓ Check disk space availability
Enable debug logging by setting the environment variable:
DEBUG=youtube-transcript-mcp node index.jsAverage transcript extraction time: 1-3 seconds
Memory usage: ~50MB
Supports videos up to 12+ hours in length
Handles 1000+ segments efficiently
Contributions are welcome! Please follow these steps:
Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request
Follow existing code style
Add tests for new features
Update documentation as needed
Ensure all tests pass before submitting PR
MIT License - see LICENSE file for details
youtubei.js - Excellent YouTube API implementation
Model Context Protocol - MCP SDK and specification
Anthropic - For creating Claude and the MCP protocol
Support for multiple language transcripts
Batch processing for multiple videos
Transcript translation capabilities
Export to SRT/VTT subtitle formats
Caching for improved performance
Support for playlist extraction
Real-time transcript streaming
Custom formatting options
For issues, questions, or suggestions:
📧 Contact: tanush@cintra.run
🎉 Initial release
✨ Transcript extraction with youtubei.js
⏱️ Timestamp support
📊 Metadata extraction
💾 File saving capability
🔧 MCP protocol implementation
Made with ❤️ by the Open Source Community
Star ⭐ this repo if you find it useful!
Extract transcript from a YouTube video URL or video ID
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | YouTube video URL or video ID (e.g., https://youtube.com/watch?v=VIDEO_ID or just VIDEO_ID) | |
| include_timestamps | No | Include timestamps in the transcript (default: false) |
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 only says 'extract transcript' and does not mention important behavioral traits such as requiring available captions/subtitles, failing for videos without transcripts, or whether any other side effects occur.
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 a single, front-loaded sentence with no filler. It states the core purpose immediately and avoids unnecessary detail.
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?
Although the tool is simple and the schema covers parameters fully, the absence of an output schema, annotations, and sibling comparisons leaves gaps. The description does not explain what the returned transcript looks like, when it will fail, or why an agent should choose this over get_transcript_with_metadata.
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 schema fully describes both parameters (url and include_timestamps), so the description does not need to add much. It does reinforce that url accepts either a full URL or a bare video ID, but it adds no new meaning beyond the schema.
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 action ('Extract transcript') and the resource ('YouTube video URL or video ID'). It is specific and unambiguous, though it does not explicitly distinguish itself from get_transcript_with_metadata, which appears to be the closest sibling alternative.
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?
No guidance is provided about when to use this tool versus get_transcript_with_metadata or save_transcript. An agent would have to infer the appropriate choice from sibling names alone, which may be ambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Extract transcript with detailed metadata including duration and word count
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | YouTube video URL or video ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of behavioral disclosure. 'Extract' indicates a read operation with no apparent side effects, and the description states what the result contains. However, it does not mention return format, authentication requirements, rate limits, or error behavior, though these are less critical for a simple retrieval tool.
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 a single front-loaded sentence with no filler. It names the action, the resource, and the key distinguishing output details, so every word earns its place.
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?
For a one-parameter retrieval tool with no output schema, the description is largely complete: the required input is fully defined in the schema, and the return value is summarized with concrete metadata examples. It does not enumerate all metadata fields or specify the output format, but the tool's simplicity makes this a minor gap rather than a significant one.
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 schema covers 100% of the single parameter with a clear description ('YouTube video URL or video ID'), so the baseline is 3. The tool description adds no additional parameter-level meaning beyond what the schema already provides.
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 uses a specific verb ('Extract') and resource ('transcript') and adds the distinguishing detail 'detailed metadata including duration and word count.' This clearly separates it from the sibling tool get_transcript, which presumably returns only a plain transcript, and from save_transcript, which implies persistence.
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 this tool is appropriate when a transcript plus metadata such as duration and word count is needed, but it never explicitly states when to prefer it over get_transcript or save_transcript. The agent must infer the distinction from the tool name and the word 'metadata.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Extract and save transcript to a file
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | YouTube video URL or video ID | |
| filename | Yes | Filename to save the transcript (without extension) | |
| with_timestamps | No | Save version with timestamps (default: true) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing side effects. It does state that the tool writes to a file, but it does not mention overwrite behavior, file path/location handling, what happens on duplicate filenames, or whether any output is returned after saving. This is a meaningful gap for a file-writing tool.
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 a single, front-loaded sentence with no filler or repetition. Every word contributes to the core meaning, making it easy for an agent to parse 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?
The tool is simple and the schema covers all three parameters, but the description omits important behavioral context such as file overwrite behavior, return value, and any distinction between the timestamped and plain transcript variants beyond the schema's brief boolean description. It is adequate for basic invocation but leaves gaps an agent might need to resolve.
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 100%, so the input schema already documents url, filename, and with_timestamps. The description adds no additional parameter semantics, but none are needed given the schema's completeness; baseline 3 is appropriate.
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 states a clear action ('extract and save') and resource ('transcript'), and identifies the file as the destination, which distinguishes it from the sibling tools that return transcripts rather than persist them. It does not explicitly name the siblings, but the verb and file destination make the core 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 when to use this tool: when a transcript needs to be saved to a file, as opposed to the get_transcript siblings which likely return content directly. However, it provides no explicit guidance about when to choose this over get_transcript_with_metadata or how to decide between timestamped and non-timestamped saves.
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.
v1.0.0get_transcriptget_transcript_with_metadatasave_transcriptScored across 3 tools
The tools are mostly distinct: one returns raw transcript, another adds metadata, and the third saves to a file. However, get_transcript and get_transcript_with_metadata overlap heavily since the latter is a superset, which could cause an agent to pick the wrong one for a simple transcript request.
All tool names follow a consistent verb_noun pattern in snake_case: get_transcript, get_transcript_with_metadata, save_transcript. The naming clearly indicates the action and target, with no mixed conventions or vague verbs.
Three tools is well-scoped for a server dedicated to YouTube transcript extraction. Each tool serves a clear purpose—basic retrieval, retrieval with metadata, and saving to file—without unnecessary bloat.
The core workflow of extracting and saving transcripts is covered. Minor gaps exist such as language selection, timestamped segments, or listing available transcript tracks, but these are extensions rather than fundamental missing pieces for the stated purpose.
YouTube transcripts, search, channels, playlists and bulk transcript jobs for AI agents. 14 tools.
YouTube transcripts, search, channel browsing, and playlists for AI agents via MCP.
Any video URL to LLM-ready transcript. ASR built in, no captions needed. TikTok, X, TED and more.
YouTube transcripts, search, channel/playlist listings and upload tracking for AI agents. No signup.
