🎥 YouTube Video Intelligence Suite

Professional-grade YouTube transcript extraction and AI-powered video analysis for Claude Desktop

A comprehensive Model Context Protocol (MCP) server that transforms YouTube videos into intelligent, searchable content through advanced transcript extraction and AI analysis. No API keys required - works seamlessly with Claude Desktop's built-in intelligence.

� Current Version: v0.5.0

Latest Enhancement: VTT→SRV1 Migration with Enhanced Quality Analysis

Smart Format Fallback: SRV1 → JSON3 → TTML → VTT priority chain for superior quality
Advanced Quality Analysis: Comprehensive safety validation with quality scoring
Enhanced Deduplication: Intelligent duplicate detection with effectiveness tracking
Professional-Grade Output: Industry-standard transcript quality with safety validation

🚀 Quick Start

Prerequisites

Python 3.10+
uv package manager
Claude Desktop app
No API keys required! ✨

Installation & Testing

# Clone and setup
git clone <repository-url>
cd mcp-youtube-transcript
uv sync

# Quick test (optional but recommended)
python quick_test.py

# Or use automated setup
./setup.sh

Claude Desktop Configuration

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
    "mcpServers": {
        "youtube-transcript": {
            "command": "uv",
            "args": [
                "run",
                "--directory",
                "/FULL/PATH/TO/mcp-youtube-transcript",
                "python",
                "main.py"
            ]
        }
    }
}

⚠️ Replace /FULL/PATH/TO/mcp-youtube-transcript with your actual project path!

Test in Claude Desktop

Get the transcript from: https://www.youtube.com/watch?v=jNQXAC9IVRw

📖 For complete setup instructions, see DEPLOYMENT_GUIDE.md

🛠️ Standalone Extraction Tools

NEW: Professional CLI Tool (Decoupled from MCP)

A complete standalone extraction system with transcript + comment support:

# Extract transcript only
uv run python scripts/youtube_extract.py <video-url>

# Extract transcript + comments
uv run python scripts/youtube_extract.py <video-url> --comments --max-comments 100

# With custom options
uv run python scripts/youtube_extract.py <video-url> \
  --comments \
  --max-comments 50 \
  --comment-replies \
  --format both \
  --output ./data

# Minimal format optimized for Claude
uv run python scripts/youtube_extract.py <video-url> --minimal

Features:

✅ Transcript extraction (multi-format fallback)
✅ Comment extraction with threading
✅ Quality analysis and metrics
✅ Multiple output formats (Markdown, JSON)
✅ Completely standalone (no MCP dependency)
✅ Production-ready error handling

📖 Full documentation: docs/STANDALONE_CLI.md

Legacy Tool (MCP-focused)

# Basic extraction for MCP resources
uv run scripts/youtube_to_mcp.py <video-url>

# Output saved to resources/transcripts/ as markdown files

🌟 Features

🏗️ Complete MCP Architecture

8 Core Tools - Professional transcript extraction + advanced analysis
6 Smart Resources - Zero-token access to cached data and analytics
3 Essential Prompts - Guided conversation starters for common workflows
Enhanced Quality Pipeline - Advanced deduplication and safety validation
Rich Metadata - Comprehensive video information with engagement metrics
Modular Design - Shared extraction module for consistency across interfaces

🚀 Enhanced Extraction Pipeline (v0.5.0)

Smart Format Fallback - SRV1 → JSON3 → TTML → VTT priority chain for best quality
Advanced Quality Analysis - Comprehensive safety validation with quality metrics
Intelligent Deduplication - Advanced algorithms with effectiveness tracking
HTML Entity Support - Proper decoding across all subtitle formats
Context-Aware Validation - Video metadata integration for enhanced assessment
Professional-Grade Output - Industry-standard transcript quality

Core Transcript Extraction

Multi-format YouTube URL support (youtube.com, youtu.be, embed URLs)
Multi-language transcript extraction with automatic fallbacks
Robust error handling with detailed quality analysis
yt-dlp based extraction for universal reliability (no cloud server blocking)
Enhanced text processing with proper HTML entity decoding

🔧 8 Core Tools

Transcript Extraction

get_youtube_transcript - Primary extraction with quality analysis
get_youtube_transcript_ytdlp - Alternative extraction method
get_plain_text_transcript - Clean text output with deduplication
get_transcript_quality_analysis - Comprehensive quality metrics

Video Analysis

get_enhanced_video_metadata - Rich video information and engagement metrics
create_mcp_resource_from_transcript_v2 - Save transcripts as MCP resources

System Tools

search_transcript - Find content within transcripts
get_system_status - Server health and configuration info

📊 6 Smart Resources

Access cached data and enhanced content through MCP resources:

transcripts://available - Browse all available transcripts
transcripts://content/{video_id} - Access specific transcript content
transcripts://cached - View all cached transcripts with metadata
transcripts://quality_report - System-wide quality analytics and trends
analytics://history - View previous analysis results and usage patterns
system://status - Server status and configuration information

🎯 3 Essential Prompts

Guided workflows for comprehensive analysis:

transcript_analysis_workshop - Deep-dive video content analysis
study_notes_generator - Create structured study materials from videos
video_insight_explorer - Comprehensive video exploration and insights

🎨 What You Can Do

Basic Operations

"Get the transcript from: [YouTube URL]"
"Extract transcript from this video: [URL]"
"Show me the quality analysis for: [URL]"

Advanced Analysis

"Analyze this video for key points: [URL]"
"Create study notes from: [Educational video URL]"
"Generate a comprehensive analysis of: [URL]"
"Compare the arguments in these videos: [URL1] [URL2]"

Resource Access

"Show me all cached transcripts"
"What's the quality report for the system?"
"Access the transcript content for video ID: abc123"

🏗️ Architecture

Modular Design

src/youtube_core/ - Standalone extraction library (NEW!)
extractor.py - Core extraction class
transcript.py - Transcript extraction logic
comments.py - Comment retrieval system
quality.py - Quality analysis engine
formatters.py - Output formatting
config.py - Configuration management
streamlined_server.py - Complete MCP server implementation
main.py - Entry point for Claude Desktop integration
scripts/youtube_extract.py - Professional standalone CLI tool
scripts/youtube_to_mcp.py - Legacy MCP-focused tool

Quality-First Approach

Smart Format Selection - Automatic fallback ensures best available quality
Advanced Deduplication - Sophisticated algorithms remove caption overlaps
Safety Validation - Multi-layer content quality checks
Professional Output - Industry-standard transcript formatting

Standalone Core Library

The new youtube_core module provides:

Zero MCP dependency - Use independently anywhere
Programmatic API - Import and use in your Python projects
Complete functionality - Transcript + comments + metadata + quality analysis
Production-ready - Error handling, timeouts, retries

from youtube_core import YouTubeExtractor

extractor = YouTubeExtractor()
result = extractor.extract(url, include_comments=True)

Zero Dependencies Bloat

yt-dlp - Reliable transcript extraction (no cloud server blocking)
mcp - Model Context Protocol integration (optional for standalone use)
Pure Python - No heavy AI libraries or API dependencies

📈 Version History

v0.5.0 (Current) - VTT→SRV1 Migration

Smart format fallback system (SRV1 → JSON3 → TTML → VTT)
Enhanced quality analysis with safety validation
Advanced deduplication with effectiveness tracking
Professional-grade transcript quality

v0.4.0 - Complete yt-dlp Migration

Removed youtube-transcript-api dependency
Universal reliability with yt-dlp-only approach
Enhanced VTT processing and deduplication
Eliminated cloud server blocking issues

v0.3.0 - Enhanced Quality & Rich Resources

Major quality improvements (5,700% richer content)
Advanced deduplication algorithms
Comprehensive resource architecture
Enhanced metadata integration

🔧 Troubleshooting

Common Issues

"Command not found: uv"

   curl -LsSf https://astral.sh/uv/install.sh | sh
   source ~/.zshrc

Claude Desktop not recognizing server

Verify full path in claude_desktop_config.json
Restart Claude Desktop completely
Run python quick_test.py to validate setup

Transcript extraction fails

Check internet connection
Verify video has available transcripts
Try alternative extraction method

Validation

# Test everything works
python quick_test.py

# Test manual extraction
uv run scripts/youtube_to_mcp.py https://www.youtube.com/watch?v=jNQXAC9IVRw

📚 Documentation

DEPLOYMENT_GUIDE.md - Complete setup instructions
docs/ - Comprehensive documentation
CHANGELOG.md - Version history and changes
SHARING_SUMMARY.md - Repository sharing guide

🎯 Success Criteria

You should be able to:

[x] Extract transcripts from any YouTube video
[x] Perform AI analysis without API keys
[x] Access cached content through MCP resources
[x] Use guided prompts for complex analysis
[x] Run standalone extraction scripts
[x] Get professional-grade transcript quality

---

🎉 Transform YouTube videos into intelligent, searchable content with professional-grade quality! 🎥✨

mcp-youtube-transcript