YouTube Transcript DL MCP Server
This server provides MCP tools for extracting and formatting YouTube video transcripts, with multiple transports and deployment options.
Extract a single video's transcript in text, JSON, or SRT format (
get_transcript)Bulk extract transcripts from multiple YouTube videos (
get_bulk_transcripts)Extract transcripts from all videos in a playlist (
get_playlist_transcripts) โ though playlist support is unfinishedConvert existing transcript data between text, JSON, and SRT formats (
format_transcript)List all available transcripts for a video (
list_transcripts)View cache statistics (
get_cache_stats) and clear the cache (clear_cache)Run as an MCP server over stdio, SSE, or HTTP transports
Supports language selection for transcripts
Deployable via Docker and npm package, with caching, rate limiting, and configuration options
Offers full containerization support with Docker deployment options, including health checks, Docker Compose configuration, and container registry distribution via GitHub Container Registry.
Integrates with ESLint for code style enforcement and quality control in the development workflow.
Integrates with GitHub for issue tracking, documentation hosting, and container registry distribution through GitHub Container Registry.
Distributed as an npm package for easy installation and integration, with both global CLI usage and programmatic API access.
Built with TypeScript for full type safety, providing strongly-typed interfaces for transcript data and programmatic usage of the service.
Extracts and processes YouTube video transcripts with support for single videos, bulk processing, and playlists. Provides transcript data in multiple formats (text, JSON, SRT) and supports multi-language extraction.
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 DL MCP Server get transcript for https://youtu.be/dQw4w9WgXcQ in English"
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.
๐ฌ YouTube Transcript DL MCP Server
Deprecated and incomplete: the published package does not contain every runtime dependency used by the repository, playlist extraction is unfinished, and the test suite is not fully passing. Do not use this as a production MCP server. The package remains available only for historical compatibility.
A comprehensive MCP (Model Context Protocol) server for extracting YouTube video transcripts with support for multiple transports (stdio, SSE, HTTP), Docker deployment, and npm package distribution.
โจ Features
๐ฏ Multiple Transport Support: stdio, Server-Sent Events (SSE), and HTTP
๐น Transcript Extraction: Single-video extraction; playlist support is unfinished
๐ Multi-language Support: Extract transcripts in different languages
๐ Multiple Output Formats: Text, JSON, and SRT subtitle formats
๐ High Performance: Built-in caching and rate limiting
๐ณ Docker Ready: Full containerization support
๐ฆ npm Package: Easy installation and distribution
๐งช Test Suite: Partial coverage; not all tests currently pass
๐ง TypeScript: Full type safety and modern JavaScript features
Related MCP server: youtube-mcp
๐ฆ Installation
๐ง As an npm package
npm install -g yt-transcript-dl-mcp๐ ๏ธ From source
git clone https://github.com/jedarden/yt-transcript-dl-mcp.git
cd yt-transcript-dl-mcp
npm install
npm run build๐ณ Docker
# From GitHub Container Registry (recommended)
docker pull ghcr.io/jedarden/yt-transcript-dl-mcp:latest
docker run -p 3001:3001 -p 3002:3002 ghcr.io/jedarden/yt-transcript-dl-mcp:latest --multi-transport
# Build from source
docker build -t yt-transcript-dl-mcp .
docker run -p 3001:3001 -p 3002:3002 yt-transcript-dl-mcp --multi-transport๐ Usage
๐ฅ๏ธ MCP Server
Start the MCP server in different modes:
# Stdio mode (default)
yt-transcript-dl-mcp start
# SSE mode
yt-transcript-dl-mcp start --transport sse --port 3000
# HTTP mode
yt-transcript-dl-mcp start --transport http --port 3000
# With verbose logging
yt-transcript-dl-mcp start --verbose๐ป CLI Tool
Test the server with a sample video:
# Test with a YouTube video
yt-transcript-dl-mcp test dQw4w9WgXcQ
# Test with different language
yt-transcript-dl-mcp test dQw4w9WgXcQ --language es
# Test with different format
yt-transcript-dl-mcp test dQw4w9WgXcQ --format srt๐ง Programmatic Usage
import { YouTubeTranscriptService } from 'yt-transcript-dl-mcp';
const service = new YouTubeTranscriptService();
// Extract single video transcript
const result = await service.getTranscript('dQw4w9WgXcQ', 'en', 'json');
console.log(result);
// Bulk processing
const bulkResult = await service.getBulkTranscripts({
videoIds: ['dQw4w9WgXcQ', 'jNQXAC9IVRw'],
outputFormat: 'json',
language: 'en'
});
console.log(bulkResult);๐ ๏ธ MCP Tools
The server provides the following MCP tools:
get_transcript
Extract transcript from a single YouTube video.
Parameters:
videoId(required): YouTube video ID or URLlanguage(optional): Language code (default: 'en')format(optional): Output format - 'text', 'json', or 'srt' (default: 'json')
get_bulk_transcripts
Extract transcripts from multiple YouTube videos.
Parameters:
videoIds(required): Array of YouTube video IDs or URLslanguage(optional): Language code (default: 'en')outputFormat(optional): Output format - 'text', 'json', or 'srt' (default: 'json')includeMetadata(optional): Include metadata in response (default: true)
get_playlist_transcripts
Extract transcripts from all videos in a YouTube playlist.
Parameters:
playlistId(required): YouTube playlist ID or URLlanguage(optional): Language code (default: 'en')outputFormat(optional): Output format - 'text', 'json', or 'srt' (default: 'json')includeMetadata(optional): Include metadata in response (default: true)
format_transcript
Format existing transcript data into different formats.
Parameters:
transcript(required): Transcript data arrayformat(required): Output format - 'text', 'json', or 'srt'
get_cache_stats
Get cache statistics and performance metrics.
clear_cache
Clear the transcript cache.
โ๏ธ Configuration
๐ Environment Variables
# Server configuration
PORT=3000
HOST=0.0.0.0
MCP_TRANSPORT=stdio
# CORS settings
CORS_ENABLED=true
CORS_ORIGINS=*
# Rate limiting
RATE_LIMIT_WINDOW=900000 # 15 minutes in ms
RATE_LIMIT_MAX=100
# Caching
CACHE_ENABLED=true
CACHE_TTL=3600 # 1 hour in seconds
CACHE_MAX_SIZE=1000
# Logging
LOG_LEVEL=info
LOG_FORMAT=simple๐ Configuration File
Create a config.json file:
{
"port": 3000,
"host": "0.0.0.0",
"cors": {
"enabled": true,
"origins": ["*"]
},
"rateLimit": {
"windowMs": 900000,
"max": 100
},
"cache": {
"enabled": true,
"ttl": 3600,
"maxSize": 1000
},
"logging": {
"level": "info",
"format": "simple"
}
}๐ณ Docker Deployment
๐ Docker Compose
version: '3.8'
services:
yt-transcript-mcp:
build: .
ports:
- "3000:3000"
environment:
- NODE_ENV=production
- PORT=3000
- LOG_LEVEL=info
restart: unless-stopped
healthcheck:
test: ["CMD", "node", "dist/health-check.js"]
interval: 30s
timeout: 10s
retries: 3Health Checks
The Docker container includes built-in health checks:
# Check container health
docker ps
docker exec <container-id> node dist/health-check.jsDevelopment
Setup
git clone <repository-url>
cd yt-transcript-dl-repo
npm installRunning Tests
# Run all tests
npm test
# Run tests with coverage
npm run test:coverage
# Run specific test suites
npm run test:unit
npm run test:integration
npm run test:e2e
# Watch mode
npm run test:watchBuilding
# Build TypeScript
npm run build
# Development mode with watch
npm run dev
# Linting
npm run lint
npm run lint:fixTesting the MCP Server
# Test stdio transport
./scripts/test-stdio.sh
# Test with sample video
npm run test:sampleAPI Documentation
Response Format
All transcript responses follow this structure:
interface TranscriptResponse {
videoId: string;
title?: string;
language: string;
transcript: TranscriptItem[];
metadata?: {
extractedAt: string;
source: string;
duration?: number;
error?: string;
};
}
interface TranscriptItem {
text: string;
start: number;
duration: number;
}Error Handling
The server handles various error scenarios:
Video not found: Returns empty transcript with error in metadata
Private videos: Graceful error handling with descriptive messages
Rate limiting: Built-in delays and retry logic
Network errors: Automatic retries with exponential backoff
Performance
Benchmarks
Single video extraction: < 5 seconds
Bulk processing: < 2 seconds per video
Concurrent requests: 90%+ success rate for 10 concurrent requests
Memory usage: < 512MB under normal load
Cache hit ratio: 70%+ for repeated requests
Optimization
LRU Cache: Configurable TTL and size limits
Rate Limiting: Prevents API abuse
Concurrent Processing: Optimized for bulk operations
Memory Management: Efficient garbage collection
Troubleshooting
Common Issues
Video not found: Check if video is public and has captions
Rate limiting: Reduce concurrent requests or increase delays
Memory issues: Reduce cache size or clear cache regularly
Network errors: Check internet connection and firewall settings
Debug Mode
Enable debug logging:
export LOG_LEVEL=debug
yt-transcript-dl-mcp start --verboseLogs
Check logs in the logs/ directory:
tail -f logs/combined.log
tail -f logs/error.logContributing
Fork the repository
Create a feature branch
Write tests for new functionality
Ensure all tests pass
Submit a pull request
Code Style
Use TypeScript for all code
Follow ESLint configuration
Write comprehensive tests
Add JSDoc comments for public APIs
Use conventional commit messages
License
MIT License - see LICENSE file for details.
Support
GitHub Issues: Report bugs and feature requests
Documentation: Full API documentation
Examples: Usage examples
Changelog
v1.0.0
Initial release
MCP server with stdio, SSE, and HTTP transports
Single video and bulk transcript extraction
Docker containerization
Comprehensive test suite
TypeScript support
Caching and rate limiting
Multiple output formats (text, JSON, SRT)
Available Tools
7 toolsclear_cacheB
Clear the transcript cache
Inputs: no named parameters.
format_transcriptB
Format existing transcript data into different formats
Inputs: transcript (required), format (required).
get_bulk_transcriptsC
Extract transcripts from multiple YouTube videos
Inputs: videoIds (required), language, outputFormat, includeMetadata.
get_cache_statsB
Get cache statistics and performance metrics
Inputs: no named parameters.
get_playlist_transcriptsC
Extract transcripts from all videos in a YouTube playlist
Inputs: playlistId (required), language, outputFormat, includeMetadata.
get_transcriptC
Extract transcript from a single YouTube video
Inputs: videoId (required), language, format.
list_transcriptsC
List all available transcripts for a YouTube video
Inputs: videoId (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogโฆ
TDQS
Scored across 7 tools
Each tool has a clearly distinct purpose with no ambiguity: clear_cache handles cache management, format_transcript processes existing data, get_bulk_transcripts extracts from multiple videos, get_cache_stats provides metrics, get_playlist_transcripts targets playlists, get_transcript handles single videos, and list_transcripts enumerates available transcripts. The descriptions clearly differentiate between single-video, multi-video, playlist, cache, and formatting operations.
All tools follow a consistent verb_noun pattern with snake_case throughout: clear_cache, format_transcript, get_bulk_transcripts, get_cache_stats, get_playlist_transcripts, get_transcript, and list_transcripts. The naming is predictable and readable, using verbs like 'clear', 'format', 'get', and 'list' consistently across the set.
With 7 tools, the count is well-scoped for a YouTube transcript server, covering core operations like extraction (single, bulk, playlist), caching, formatting, and listing without bloat. Each tool earns its place by addressing a specific aspect of transcript handling, making the set neither too thin nor too heavy for the domain.
The tool surface is nearly complete for transcript extraction and management, covering key operations: extraction (single, bulk, playlist), cache management (clear, stats), formatting, and listing. A minor gap exists in update or delete operations for transcripts, but agents can work around this, and the core workflows are well-covered for the server's purpose.
Maintenance
Related MCP Connectors
An MCP server that gives any LLM or agent clean YouTube transcripts on demand: a single video, a whole channel, or a playlist, plus AI cleanup of auto-generated captions. API-key auth, credit-based, same backend as the public v1 API. Get a free API key with 25 free credits at youtubetranscriptdownload.com/account.
An MCP server that provides tools to discover and retrieve podcast episodes transcripts.
MCP server for RiverScript, an AI transcription platform - fetches transcripts shared via a link.
Real-time YouTube transcripts, comments, channels & video search MCP. Local npx or hosted OAuth.
Related MCP Servers
- AlicenseAqualityDmaintenanceAn MCP server that enables users to retrieve YouTube transcripts and perform video or channel searches without requiring Google API keys. It supports transcript chunking and provides tools for detailed video content analysis and channel metadata extraction.530 npm4MIT
- AlicenseBqualityBmaintenanceAn MCP server that enables the extraction of transcripts and detailed metadata from YouTube videos. It allows users to retrieve video information like titles and descriptions, as well as transcripts with optional timestamps and language selection.2MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for fetching YouTube video transcripts without an API key.GPL 3.0
- FlicenseNot gradedqualityDmaintenanceMCP server providing tools to fetch YouTube video transcripts with metadata, supporting direct YouTube transcripts and audio transcription via multiple backends (whisper, AssemblyAI, OpenAI, Gemini).-