YouTube MCP Server

Un servidor basado en Python para el Model Context Protocol (MCP) que extrae contenido educativo de videos de YouTube (transcripciones y fotogramas visualmente significativos) y lo pone a disposición de asistentes de IA como Claude, ChatGPT y cualquier cliente compatible con MCP.

Qué Hace

Dale a un asistente de IA una URL de YouTube y podrá:

1. Leer la transcripción — Subtítulos completos con marcas de tiempo, listos para resumir, hacer preguntas y respuestas o analizar el contenido.

2. Ver el video — Un pipeline de visión por computadora de 5 fases extrae los fotogramas más informativos, los puntúa según su calidad, elimina duplicados y los devuelve como JPEG codificados en base64 que la IA puede «ver».

Sin descargas manuales. Sin copiar y pegar. Solo pega una URL y haz preguntas.

Herramientas

get_transcript

Obtiene los subtítulos del video usando youtube-transcript-api.

Parámetros:

• url (obligatorio) — URL del video de YouTube

• language (opcional, por defecto: "en") — Idioma de subtítulos preferido

• prefer_manual (opcional, por defecto: true) — Prefiere subtítulos escritos manualmente sobre los generados automáticamente

Devuelve: Un bloque de transcripción limpio y con marcas de tiempo:

[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

Ejecuta un pipeline completo de análisis de video para sacar a la luz los momentos visuales más significativos.

Parámetros:

• url (obligatorio) — URL del video de YouTube

• max_frames (opcional, por defecto: 20) — Número máximo de fotogramas a devolver (límite máximo: 40)

• scene_threshold (opcional, por defecto: 0.25) — Sensibilidad de detección de escenas de FFmpeg

• output_width (opcional, por defecto: 640) — Ancho de los JPEG devueltos (altura proporcional)

• min_importance_score (opcional, por defecto: 0.35) — Puntuación mínima de calidad compuesta

Devuelve:

• Metadatos: video_id, duration_seconds, pipeline_stats, fallback_used

• Bloques de fotogramas: cada uno incluye timestamp_ms, composite_score y una imagen JPEG codificada en base64

• Un índice que enumera cada fotograma devuelto con su marca de tiempo y puntuación

El Pipeline de Fotogramas (5 Fases)

Inicio Rápido

Requisitos Previos

• Python 3.11

• ffmpeg — procesamiento de video

• Tesseract OCR — detección de texto en fotogramas

macOS:

brew install ffmpeg tesseract

Ubuntu / Linux:

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

Windows: Descarga ffmpeg y Tesseract y añádelos a tu PATH.

Verifica:

ffmpeg -version
tesseract --version

Instalación

# 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

Configuración

Crea un archivo .env en la raíz del proyecto:

LOG_LEVEL=DEBUG
MCP_HTTP_PORT=8000

Ajuste opcional (se cargan los valores predeterminados de config.py si se omiten):

Iniciar el Servidor

python server.py

El servidor se inicia en http://localhost:8000.

Conexión con Claude.ai (Local)

1. Inicia el servidor: python server.py

2. Ve a Claude.ai → Configuración → Integraciones → Añadir servidor MCP

3. Introduce: http://localhost:8000/mcp

Para que Claude alojado en la nube pueda acceder a tu servidor, tendrás que exponerlo públicamente (consulta Despliegue más abajo).

Endpoints de la API

Estructura del Proyecto

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

Flujo de Trabajo de Desarrollo

Este proyecto se ha construido en 9 fases independientes, cada una con su propio archivo de prueba y paso de verificación:

Regla de oro: Cada fase se verifica antes de continuar. Ejecuta python test_stage{N}.py para validar.

Despliegue

El soporte de Docker está planificado pero aún no está configurado. Esta sección se actualizará cuando se complete la contenedorización.

Por ahora, el servidor se ejecuta directamente en cualquier máquina con Python 3.11, ffmpeg y Tesseract instalados. Opciones de alojamiento recomendadas cuando Docker esté listo:

• Railway

• Fly.io

• Render

Una vez desplegado, actualiza la URL de integración de Claude.ai a:

https://YOUR-DEPLOYMENT-URL/mcp

Notas de Diseño

• Todo el registro de eventos va solo a stderr. stdout está reservado exclusivamente para la comunicación MCP.

• Seguro para subprocesos: El pipeline get_video_frames utiliza un threading.Semaphore(1) para evitar que las descargas simultáneas saturen el sistema.

• Limpieza automática: Los archivos temporales creados durante el procesamiento de video se eliminan después de cada ejecución.

• Validación estricta: Los ID de video se validan con ^[A-Za-z0-9_-]{11}$. Las URL de solo listas de reproducción, las URL de canales y las entradas mal formadas se rechazan con mensajes de error claros.

• Degradación elegante: Si todos los fotogramas puntúan por debajo del umbral mínimo de importancia, el pipeline recurre a los 5 mejores fotogramas y marca fallback_used: true.

Licencia

MIT © Ayush Mamgain

Agradecimientos

Construido con FastMCP, Starlette, yt-dlp, youtube-transcript-api y OpenCV.