YouTube MCP Server

Python-сервер на базе Model Context Protocol (MCP), который извлекает образовательный контент из видео YouTube — транскрипты и визуально значимые кадры — и предоставляет его ИИ-ассистентам, таким как Claude, ChatGPT и любому MCP-совместимому клиенту.

Что он делает

Дайте ИИ-ассистенту URL видео YouTube, и он сможет:

1. Прочитать транскрипт — Полные субтитры с таймкодами, готовые для суммаризации, Q&A или анализа контента.

2. Увидеть видео — Конвейер компьютерного зрения из 5 этапов извлекает наиболее информативные кадры, оценивает их качество, удаляет дубликаты и возвращает их в виде JPEG-изображений в кодировке base64, которые ИИ может «увидеть».

Без ручного скачивания. Без копирования и вставки. Просто вставьте URL и задавайте вопросы.

Инструменты

get_transcript

Получает субтитры видео с помощью youtube-transcript-api.

Параметры:

• url (обязательный) — URL видео YouTube

• language (необязательный, по умолчанию: "en") — Предпочитаемый язык субтитров

• prefer_manual (необязательный, по умолчанию: true) — Предпочитать субтитры, созданные вручную, автоматически сгенерированным

Возвращает: Чистый блок транскрипта с таймкодами:

[00:00:00] So I want to start by offering you a free ...
[00:00:15] The key insight here is that ...

get_video_frames

Запускает полный конвейер анализа видео, чтобы выявить наиболее значимые визуальные моменты.

Параметры:

• url (обязательный) — URL видео YouTube

• max_frames (необязательный, по умолчанию: 20) — Максимальное количество возвращаемых кадров (жёсткий лимит: 40)

• scene_threshold (необязательный, по умолчанию: 0.25) — Чувствительность обнаружения смены сцен FFmpeg

• output_width (необязательный, по умолчанию: 640) — Ширина возвращаемых JPEG-изображений (высота пропорциональна)

• min_importance_score (необязательный, по умолчанию: 0.35) — Минимальный совокупный балл качества

Возвращает:

• Метаданные: video_id, duration_seconds, pipeline_stats, fallback_used

• Блоки кадров: каждый содержит timestamp_ms, composite_score и JPEG-изображение в кодировке base64

• Индекс всех возвращённых кадров с их таймкодами и баллами

Конвейер обработки кадров (5 этапов)

Быстрый старт

Предварительные требования

• Python 3.11

• ffmpeg — обработка видео

• Tesseract OCR — распознавание текста на кадрах

macOS:

brew install ffmpeg tesseract

Ubuntu / Linux:

sudo apt-get install ffmpeg tesseract-ocr tesseract-ocr-eng

Windows: Скачайте ffmpeg и Tesseract, затем добавьте оба в переменную PATH.

Проверка:

ffmpeg -version
tesseract --version

Установка

# Clone the repository
git clone https://github.com/Ayush-Mamgain/youtube-mcp-server.git
cd youtube-mcp-server

# Create a virtual environment
python3 -m venv venv
source venv/bin/activate        # macOS / Linux
# venv\Scripts\activate      # Windows

# Install dependencies
pip install -r requirements.txt

Конфигурация

Создайте файл .env в корне проекта:

LOG_LEVEL=DEBUG
MCP_HTTP_PORT=8000

Дополнительная настройка (используются значения по умолчанию из config.py, если параметры не указаны):

Запуск сервера

python server.py

Сервер запускается по адресу http://localhost:8000.

Подключение к Claude.ai (локально)

1. Запустите сервер: python server.py

2. Перейдите в Claude.ai → Настройки → Интеграции → Добавить MCP-сервер

3. Введите: http://localhost:8000/mcp

Чтобы облачный Claude мог получить доступ к вашему серверу, необходимо опубликовать его в открытом доступе (см. раздел «Развёртывание» ниже).

API-эндпоинты

Структура проекта

youtube-mcp-server/
├── server.py              # MCP entry point — FastMCP + Starlette HTTP server
├── config.py              # Loads and validates environment variables
├── logger.py              # stderr-only logging
├── url_parser.py          # Validates YouTube URLs and extracts video IDs
├── transcript.py          # Fetches captions via youtube-transcript-api
├── downloader.py          # Phase 1 — video download with yt-dlp
├── frame_extractor.py     # Phase 2 — scene-change frame extraction via ffmpeg
├── scorer.py              # Phase 3 — multi-signal frame scoring (OpenCV + Tesseract)
├── deduplicator.py        # Phase 4 — perceptual-hash deduplication
├── frame_loader.py        # Phase 5 — resize, JPEG encode, base64
├── video_frames.py        # Orchestrates Phases 1–5 with semaphore and cleanup
├── requirements.txt       # Pinned Python dependencies
└── .gitignore             # Excludes .env, venv, caches, test artifacts

Процесс разработки

Проект создавался в 9 самостоятельных этапов, каждый со своим тестовым файлом и шагом проверки:

Золотое правило: Каждый этап проверяется перед переходом к следующему. Запустите python test_stage{N}.py для проверки.

Развёртывание

Поддержка Docker запланирована, но пока не настроена. Этот раздел будет обновлён после завершения контейнеризации.

Пока сервер запускается напрямую на любой машине с установленными Python 3.11, ffmpeg и Tesseract. Рекомендуемые варианты хостинга после готовности Docker:

• Railway

• Fly.io

• Render

После развёртывания обновите URL интеграции в Claude.ai на:

https://YOUR-DEPLOYMENT-URL/mcp

Принципы проектирования

• Все логи пишутся только в stderr. stdout зарезервирован исключительно для связи через MCP.

• Потокобезопасность: Конвейер get_video_frames использует threading.Semaphore(1), чтобы предотвратить перегрузку системы параллельными загрузками.

• Автоматическая очистка: Временные файлы, создаваемые при обработке видео, удаляются после каждого запуска.

• Строгая валидация: Идентификаторы видео проверяются по шаблону ^[A-Za-z0-9_-]{11}$. URL только с плейлистами, URL каналов и некорректные входные данные отклоняются с понятными сообщениями об ошибках.

• Плавная деградация: Если все кадры набрали балл ниже минимального порога важности, конвейер возвращает 5 лучших кадров и устанавливает флаг fallback_used: true.

Лицензия

MIT © Ayush Mamgain

Благодарности

Создано с использованием FastMCP, Starlette, yt-dlp, youtube-transcript-api и OpenCV.