YouTube Transcript MCP Server

A production-ready Model Context Protocol (MCP) server that provides YouTube transcript fetching capabilities using yt-dlp CLI for reliable subtitle extraction. Bypasses YouTube's rate limiting through CLI-based implementation.

Status: Production Ready ✅

Implementation: Full CLI migration complete (September 2025)

✅ CLI-Based: Uses yt-dlp subprocess to avoid HTTP rate limiting
✅ Universal Compatibility: Time parameters work across all MCP clients
✅ Advanced Analytics: Enhanced transcript summary with content analysis
✅ Multi-Language: 100+ languages with auto-generated and manual transcripts

Features

Fetch transcripts from YouTube videos with metadata and timestamps
Time filtering - extract specific segments by start/end times
Search functionality - find text within transcripts with context
Advanced analytics - speaking pace, filler words, engagement metrics, top words
Language detection - list available transcript languages
Universal format support - handles both video IDs and full YouTube URLs
Dual transport - STDIO and HTTP transport modes
Docker support - containerized deployment with health checks

Installation

Quick Start

# Install dependencies
uv pip install -e .

# Run server (STDIO mode)
python src/server.py

# Run server (HTTP mode)
uvicorn src.server:app --host 0.0.0.0 --port 8080

Docker (Recommended)

# Build and run
docker build -t yttranscript-mcp .
docker run -d -p 8080:8080 yttranscript-mcp

# Or use docker-compose
docker-compose up -d yttranscript-mcp

# Health check
curl http://localhost:8080/health

Usage

Available Tools

get_transcript - Fetch video transcripts with optional time filtering
search_transcript - Search for specific text within transcripts
get_transcript_summary - Advanced analytics and content insights
get_available_languages - List available transcript languages

Testing Commands

# Discover tools
mcp tools .venv/bin/python src/server.py

# Basic transcript
mcp call get_transcript --params '{"video_id":"jNQXAC9IVRw"}' .venv/bin/python src/server.py

# Time-filtered transcript
mcp call get_transcript --params '{"video_id":"jNQXAC9IVRw", "start_time": 10, "end_time": 60}' .venv/bin/python src/server.py

# Search within transcript
mcp call search_transcript --params '{"video_id":"jNQXAC9IVRw", "query":"example"}' .venv/bin/python src/server.py

# Advanced analytics
mcp call get_transcript_summary --params '{"video_id":"jNQXAC9IVRw"}' .venv/bin/python src/server.py

# Available languages
mcp call get_available_languages --params '{"video_id":"jNQXAC9IVRw"}' .venv/bin/python src/server.py

MCP Client Configuration

HTTP Transport (Production)

{
  "yttranscript": {
    "command": "uvicorn",
    "args": [
      "src.server:app",
      "--host", "0.0.0.0", 
      "--port", "8080"
    ],
    "cwd": "/path/to/yttranscript_mcp"
  }
}

STDIO Transport (Development)

{
  "yttranscript": {
    "command": "uv",
    "args": [
      "run",
      "--directory", "/path/to/yttranscript_mcp",
      "src/server.py"
    ]
  }
}

Key Features

Universal Parameter Compatibility

Time filtering parameters accept multiple formats:

Integers: {"start_time": 10}
Floats: {"start_time": 10.5}
Strings: {"start_time": "10"}
Nulls: {"start_time": null} or {"start_time": "null"}

Advanced Analytics

The get_transcript_summary tool provides:

Speaking pace analysis (words per minute with descriptive labels)
Filler word detection (um, uh, like, etc.) with percentages
Content indicators (conversational, formal, high energy)
Top frequent words (excluding stop words)
Engagement metrics (questions, exclamations)
Reading time estimates at multiple speeds

CLI Implementation Benefits

No rate limiting - bypasses YouTube's HTTP restrictions
Reliable extraction - uses yt-dlp's robust parsing
Better error handling - clear error messages for various failure modes
Format flexibility - handles VTT, JSON3, and other subtitle formats

Configuration

Environment Variables

YT_TRANSCRIPT_SERVER_PORT=8080    # Server port (default: 8080)
YT_TRANSCRIPT_SERVER_HOST=0.0.0.0 # Server host (default: 0.0.0.0)
YT_TRANSCRIPT_DEBUG=false         # Debug mode

Docker Environment

# Production
docker run -e YT_TRANSCRIPT_SERVER_PORT=8080 yttranscript-mcp

# Development with auto-reload  
docker-compose --profile dev up yttranscript-mcp-dev

Dependencies

fastmcp>=0.9.0 - MCP server framework
yt-dlp>=2025.8.11 - YouTube transcript extraction via CLI
pydantic>=2.0.0 - Data validation and models
uvicorn>=0.24.0 - ASGI server for HTTP transport

This project uses uv for package management.

Troubleshooting

Tool not found: Verify @mcp.tool() decorator in tool definitions
Validation errors: Video IDs must be 11 characters, time values must be non-negative
Time filtering issues: Parameters accept multiple formats (int/float/string/null)
Transport issues: Use uvicorn for HTTP mode, python src/server.py for STDIO
No transcript available: Check with get_available_languages first

License

This project is open source and available under the MIT License.

YouTube Transcript MCP Server

YouTube Transcript MCP Server

Status: Production Ready ✅

Features

Installation

Quick Start

Docker (Recommended)

Usage

Available Tools

Testing Commands

MCP Client Configuration

HTTP Transport (Production)

STDIO Transport (Development)

Key Features

Universal Parameter Compatibility

Advanced Analytics

CLI Implementation Benefits

Configuration

Environment Variables

Docker Environment

Dependencies

Troubleshooting

License

New MCP Servers

MCP directory API