Overview

This MCP (Model Context Protocol) server extracts YouTube video metadata and transcripts, and presents them as structured context for downstream models or data pipelines. It attempts to retrieve a high-quality (manual) transcript first, then falls back to auto-generated captions or alternative sources. When transcripts are missing, the server applies deterministic fallback logic and detailed logging so callers can understand what was attempted and why a particular transcript was returned (or not).

The server is designed for ingestion into LLMs, vector databases, analytics pipelines, or any system that needs reliable, contextualized video text. It exposes an MCP-compatible interface so that tools and agents that consume model context can request, cache, and chunk video content consistently.

Features

Fetch YouTube video metadata (title, description, duration, thumbnails, channel info).
Retrieve transcripts with fallback order: manual → auto-generated → alternative extraction.
Support for partial transcripts, timestamps, and speaker segments when available.
Chunking of transcript text into MCP-friendly pieces (configurable token/character size).
Comprehensive logging and structured error handling for each extraction step.
Docker and pip-friendly installation; configurable via environment variables.
Small, dependency-minimal runtime suitable for deployment alongside model-serving stacks.
Optional caching layer to reduce repeated external requests.

Installation / Configuration

Install via pip (Python 3.8+):

# Create virtual environment (recommended)
python -m venv venv
source venv/bin/activate

# Install package (replace with package name or install from GitHub)
pip install git+https://github.com/sinjab/mcp_youtube_extract.git

Or run with Docker:

# Build locally
git clone https://github.com/sinjab/mcp_youtube_extract.git
cd mcp_youtube_extract
docker build -t mcp-youtube-extract .

# Run container
docker run -p 8080:8080 \
  -e YT_API_KEY=your_youtube_api_key \
  -e LOG_LEVEL=info \
  mcp-youtube-extract

Environment variables

YT_API_KEY (optional): YouTube Data API key to fetch metadata reliably. If omitted, the server will use public endpoints or third-party extractors where possible.
CACHE_ENABLED (true|false): Enable simple in-memory or Redis caching of transcripts.
CHUNK_SIZE (int): Number of characters (or tokens) per MCP chunk. Default: 2000.
LOG_LEVEL: info | debug | warn | error.

Example configuration file (JSON) for more advanced deployments:

{
  "yt_api_key": "YOUR_KEY",
  "cache": {
    "enabled": true,
    "backend": "redis",
    "redis_url": "redis://localhost:6379/0"
  },
  "chunk_size": 1500,
  "fallback_order": ["manual", "auto", "ocr"]
}

Available Tools / Resources

The server exposes logical tools (MCP resources) that can be requested by name:

youtube.metadata: Returns video metadata (title, channel, description, duration, thumbnails).
youtube.transcript: Primary transcript resource that implements the fallback logic and returns:
- transcript_text: full joined text
- segments: array of {start, end, text}
- source: one of [“manual”, “auto”, “extracted”, “none”]
- warnings: array of diagnostic strings
youtube.chunks: Returns an array of MCP chunks ready for model consumption with ids and boundary timestamps.
youtube.preview: Short summary or first N seconds text for fast routing.

Example MCP request (HTTP POST):

POST /mcp/resources/youtube.transcript
Content-Type: application/json

{
  "video_id": "dQw4w9WgXcQ",
  "max_length": 5000
}

Example minimal response:

{
  "video_id": "dQw4w9WgXcQ",
  "source": "auto",
  "segments": [
    {"start": 0.0, "end": 4.1, "text": "We're no strangers to love..."}
  ],
  "transcript_text": "We're no strangers to love...",
  "chunks": [
    {"id": "chunk-1", "text": "We're no strangers to love...", "start": 0.0, "end": 4.1}
  ],
  "warnings": []
}

Use Cases

LLM context augmentation: Provide accurate video transcripts and timestamps for question-answering, summarization, or private knowledge ingestion.
Media analytics: Extract speaker segments and timestamps to enable search, sentiment analysis, or topic detection across episodes.
Accessibility verification: Detect whether manual captions exist and log when only auto-generated captions are available.
Content moderation and policy enforcement: Pull transcript text into moderation workflows or automated classifiers.
Podcast / lecture indexing: Chunk transcripts into MCP-friendly pieces for vector DB embedding and semantic search.

Concrete example: Summarization pipeline

Request youtube.transcript for a lecture video.
Receive transcript chunks (chunk_size = 1500).
Embed chunks and store in your vector DB.
At query time, retrieve top chunks and send to an LLM with the original timestamps for precise citations.

Logging, Errors, and Fallback Behavior

Each extraction attempt is logged with a structured record: attempt source, elapsed time, HTTP or API errors, and final result.
Error types returned in the MCP response follow a consistent schema:
- transient: retryable network or rate-limit errors
- permanent: unavailable transcript, private video, or removed content
- partial: transcript retrieved but missing timestamps or segments
Fallback order is configurable. Default behavior prefers manual/caption-owner transcripts and only uses auto-generated captions when no manual captions exist.

Resources

Source and issues: https://github.com/sinjab/mcp_youtube_extract
Recommended: provision a YouTube Data API key for more consistent metadata responses.

If you need examples for integrating this MCP server with a specific model stack (LangChain, LlamaIndex, custom MCP agents), open an issue or refer to the GitHub repository for sample clients and connectors.

MCP Server YouTube Extractor with Transcript Fallback