🎬 YouTube Transcript DL MCP Server

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
📹 Comprehensive Transcript Extraction: Single videos, bulk processing, and playlists
🌍 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-Driven Development: Comprehensive test suite with 90%+ coverage
🔧 TypeScript: Full type safety and modern JavaScript features

📦 Installation

🔧 As an npm package

npm install -g yt-transcript-dl-mcp

🛠️ From source

git clone <repository-url>
cd yt-transcript-dl-repo
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 URL
language (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 URLs
language (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 URL
language (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 array
format (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: 3

Health Checks

The Docker container includes built-in health checks:

# Check container health
docker ps
docker exec <container-id> node dist/health-check.js

Development

Setup

git clone <repository-url>
cd yt-transcript-dl-repo
npm install

Running 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:watch

Building

# Build TypeScript
npm run build

# Development mode with watch
npm run dev

# Linting
npm run lint
npm run lint:fix

Testing the MCP Server

# Test stdio transport
./scripts/test-stdio.sh

# Test with sample video
npm run test:sample

API 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 --verbose

Logs

Check logs in the logs/ directory:

tail -f logs/combined.log
tail -f logs/error.log

Contributing

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)

🎬 YouTube Transcript DL MCP Server

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
📹 Comprehensive Transcript Extraction: Single videos, bulk processing, and playlists
🌍 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-Driven Development: Comprehensive test suite with 90%+ coverage
🔧 TypeScript: Full type safety and modern JavaScript features

📦 Installation

🔧 As an npm package

npm install -g yt-transcript-dl-mcp

🛠️ From source

git clone <repository-url>
cd yt-transcript-dl-repo
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 URL
language (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 URLs
language (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 URL
language (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 array
format (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: 3

Health Checks

The Docker container includes built-in health checks:

# Check container health
docker ps
docker exec <container-id> node dist/health-check.js

Development

Setup

git clone <repository-url>
cd yt-transcript-dl-repo
npm install

Running 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:watch

Building

# Build TypeScript
npm run build

# Development mode with watch
npm run dev

# Linting
npm run lint
npm run lint:fix

Testing the MCP Server

# Test stdio transport
./scripts/test-stdio.sh

# Test with sample video
npm run test:sample

API 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 --verbose

Logs

Check logs in the logs/ directory:

tail -f logs/combined.log
tail -f logs/error.log

Contributing

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)