YouTube Video Analyzer MCP

Servidor MCP stdio para analizar videos públicos de YouTube con Google Gemini.

Úsalo desde cualquier cliente compatible con MCP para resumir videos, extraer información con marcas de tiempo, analizar contenido hablado, inspeccionar metadatos, trabajar con VOD largos y hacer preguntas de seguimiento sobre sesiones de video largo reutilizables.

Qué puede hacer

• Analizar videos públicos de YouTube con Gemini.

• Analizar videos centrados en el habla con instrucciones de audio primero.

• Obtener metadatos normalizados de YouTube a través de la API de datos de YouTube.

• Extraer fotogramas JPEG de alta resolución de videos de YouTube con yt-dlp y ffmpeg.

• Analizar videos largos y VOD mediante tareas MCP requeridas.

• Analizar videos largos y VOD mediante trabajos en segundo plano de compatibilidad para clientes sin soporte de tareas MCP.

• Reutilizar sesiones de video largo para preguntas de seguimiento.

• Recurrir a la fragmentación de URL cuando las herramientas de descarga local no estén disponibles.

• Devolver JSON estructurado cuando proporciones un esquema de respuesta personalizado.

Related MCP server: YT-NINJA

Requisitos

• Node.js 20 o más reciente.

• Una clave de API de Gemini.

• Opcional: una clave de API de datos de YouTube para la búsqueda de metadatos.

• Opcional para el mejor soporte de video largo: yt-dlp y ffmpeg.

Inicio rápido

Usa el paquete publicado directamente desde tu cliente MCP con npx:

{
  "mcpServers": {
    "youtube-analyzer": {
      "command": "npx",
      "args": ["-y", "@ludylops/youtube-video-analyzer-mcp"],
      "env": {
        "GEMINI_API_KEY": "your_gemini_key_here",
        "YOUTUBE_API_KEY": "optional_youtube_key_here"
      }
    }
  }
}

GEMINI_API_KEY es obligatoria. YOUTUBE_API_KEY solo se requiere para get_youtube_video_metadata.

Configuración global

También puedes instalar el paquete globalmente y almacenar configuración reutilizable:

npm install -g @ludylops/youtube-video-analyzer-mcp
youtube-video-analyzer-mcp setup

Luego tu cliente MCP puede usar:

{
  "mcpServers": {
    "youtube-analyzer": {
      "command": "youtube-video-analyzer-mcp"
    }
  }
}

Paquetes

Este repositorio es un pequeño espacio de trabajo npm:

• @ludylops/video-analysis-core: lógica de análisis de video reutilizable e independiente del transporte en packages/video-analysis-core.

• @ludylops/youtube-video-analyzer-mcp: adaptador de servidor MCP stdio en la raíz del repositorio.

El servidor MCP depende del paquete principal, por lo que las aplicaciones SaaS, CLI, skills y otras integraciones pueden reutilizar la misma lógica de análisis sin depender de MCP.

Desarrollo local

npm install
npm run build
npm test
npm start

Copia .env.example a .env para ejecuciones locales:

GEMINI_API_KEY=your_gemini_api_key_here
YOUTUBE_API_KEY=your_youtube_api_key_here
GEMINI_MODEL=gemini-2.5-pro
YT_DLP_PATH=yt-dlp
MCP_LOG_LEVEL=warn

Herramientas

• get_youtube_analyzer_capabilities: inspecciona el soporte local para estrategias de video largo.

• get_youtube_video_metadata: obtiene metadatos públicos normalizados de YouTube.

• get_youtube_video_frame: extrae un fotograma JPEG de alta resolución en una marca de tiempo, con refinamiento opcional de marca de tiempo de Gemini antes de la extracción local.

• analyze_youtube_video: analiza videos cortos o ventanas de clip acotadas.

• analyze_youtube_video_audio: analiza videos centrados en el habla usando instrucciones de audio primero.

• analyze_long_youtube_video: analiza videos largos o VOD como una tarea MCP requerida.

• start_long_youtube_analysis: inicia un trabajo de video largo en segundo plano y devuelve un jobId.

• get_long_youtube_analysis_status: consulta un trabajo de video largo en segundo plano.

• get_long_youtube_analysis_result: obtiene el resultado de un trabajo de video largo en segundo plano completado.

• cancel_long_youtube_analysis: cancela un trabajo de video largo en segundo plano.

• continue_long_video_analysis: hace preguntas de seguimiento para una sesión de video largo anterior como una tarea MCP requerida.

Para entradas detalladas, estrategias y ejemplos, consulta docs/tools.md.

Videos largos

Para VOD y videos largos, llama primero a get_youtube_analyzer_capabilities.

Las herramientas nativas de video largo requieren ejecución de tareas MCP. Si tu cliente solo admite llamadas de herramienta síncronas con un tiempo de espera fijo, como 120 segundos, usa el flujo de trabajo de trabajos de compatibilidad: start_long_youtube_analysis, consulta get_long_youtube_analysis_status y luego obtén get_long_youtube_analysis_result. También puedes analizar ventanas acotadas más cortas con analyze_youtube_video.

Cuando yt-dlp, ffmpeg y un directorio temporal escribible estén disponibles, usa analyze_long_youtube_video con strategy=auto o strategy=uploaded_file. Esta ruta puede crear una sesión de archivo Gemini reutilizable y devolver un sessionId.

Cuando las herramientas de descarga local no estén disponibles, usa strategy=url_chunks. Evita descargas de medios locales, pero puede requerir más llamadas a Gemini.

Lee la guía completa en docs/long-videos.md.

Documentación

• Instalación

• Configuración

• Herramientas

• Videos largos

• Ejemplos

• Solución de problemas

• Proceso de lanzamiento

• Registro de cambios

Privacidad y limitaciones

Este servidor envía la URL de YouTube, las indicaciones y los medios relevantes o fragmentos derivados a Google Gemini. Con strategy=uploaded_file, las herramientas locales pueden descargar medios temporales antes de subirlos a Gemini. get_youtube_video_frame descarga una pequeña ventana de video temporal de alta calidad y devuelve un fotograma JPEG exacto; si se solicita refinamiento de marca de tiempo, Gemini se usa solo para elegir una marca de tiempo, no para crear píxeles de imagen. Con strategy=url_chunks, el servidor evita descargas de medios locales, pero puede hacer más llamadas a Gemini.

Los videos privados, eliminados, con restricción de edad, solo para miembros, protegidos por DRM o bloqueados por región pueden fallar según el acceso de YouTube y Gemini. Los usuarios son responsables de cumplir con los términos de YouTube, los términos de la API de Gemini, las reglas de derechos de autor y la ley local.

Estructura del proyecto

• packages/video-analysis-core/src: núcleo de análisis de video reutilizable.

• src/server.ts: servidor MCP y registro de herramientas.

• src/mcp-server-main.ts: punto de entrada del transporte stdio.

• src/platform-runtime: adaptadores de tiempo de ejecución utilizados por el servidor MCP.

• bin/youtube-video-analyzer-mcp.js: envoltorio CLI y flujo de configuración.

• src/test: suite de pruebas.

Contribuciones

Las contribuciones son bienvenidas. Comienza con CONTRIBUTING.md, ejecuta npm test antes de abrir cambios y actualiza CHANGELOG.md para cambios de comportamiento visibles para el usuario.

Licencia

MIT. Consulta LICENSE.