🎥 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

Related MCP server: YouTube Transcript MCP Server

🚀 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

1. "Command not found: uv"

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

2. 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

3. 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:

• Extract transcripts from any YouTube video

• Perform AI analysis without API keys

• Access cached content through MCP resources

• Use guided prompts for complex analysis

• Run standalone extraction scripts

• Get professional-grade transcript quality

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