YouTube Video Analyzer MCP

Сервер MCP stdio для анализа видео на YouTube с помощью Google Gemini.

Используйте его из любого MCP-совместимого клиента для суммаризации видео, извлечения выводов с временными метками, анализа произносимого текста, просмотра метаданных, работы с длинными VOD и уточняющих вопросов по переиспользуемым сессиям длинных видео.

Возможности

• Анализ публичных видео на YouTube с помощью Gemini.

• Анализ видео с речью с помощью инструкций, ориентированных на аудио.

• Получение нормализованных метаданных YouTube через YouTube Data API.

• Извлечение кадров в высоком разрешении из видео на YouTube с помощью yt-dlp и ffmpeg.

• Анализ длинных видео и VOD через требуемые задачи MCP.

• Анализ длинных видео и VOD через фоновые задания совместимости для клиентов без поддержки задач MCP.

• Переиспользование сессий длинных видео для уточняющих вопросов.

• Возврат к разбиению URL на фрагменты, когда локальные инструменты загрузки недоступны.

• Возврат структурированного JSON при передаче пользовательской схемы ответа.

Related MCP server: YT-NINJA

Требования

• Node.js 20 или новее.

• Ключ API Gemini.

• Необязательно: ключ YouTube Data API для поиска метаданных.

• Необязательно для наилучшей поддержки длинных видео: yt-dlp и ffmpeg.

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

Используйте опубликованный пакет напрямую из вашего MCP-клиента с помощью 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 обязателен. YOUTUBE_API_KEY требуется только для get_youtube_video_metadata.

Глобальная настройка

Вы также можете установить пакет глобально и сохранить переиспользуемую конфигурацию:

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

Затем ваш MCP-клиент может использовать:

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

Пакеты

Этот репозиторий — небольшое рабочее пространство npm:

• @ludylops/video-analysis-core: переиспользуемая транспортно-независимая логика анализа видео в packages/video-analysis-core.

• @ludylops/youtube-video-analyzer-mcp: серверный адаптер MCP stdio в корне репозитория.

Сервер MCP зависит от основного пакета, поэтому SaaS-приложения, CLI, навыки и другие интеграции могут переиспользовать ту же логику анализа, не завися от MCP.

Локальная разработка

npm install
npm run build
npm test
npm start

Скопируйте .env.example в .env для локальных запусков:

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

Инструменты

• get_youtube_analyzer_capabilities: проверяет локальную поддержку стратегий для длинных видео.

• get_youtube_video_metadata: получает нормализованные публичные метаданные YouTube.

• get_youtube_video_frame: извлекает кадр JPEG в высоком разрешении по временной метке, с необязательным уточнением временной метки через Gemini перед локальным извлечением.

• analyze_youtube_video: анализирует короткие видео или ограниченные окна клипов.

• analyze_youtube_video_audio: анализирует видео с речью с помощью инструкций, ориентированных на аудио.

• analyze_long_youtube_video: анализирует длинные видео или VOD как требуемую задачу MCP.

• start_long_youtube_analysis: запускает фоновое задание для длинного видео и возвращает jobId.

• get_long_youtube_analysis_status: опрашивает статус фонового задания для длинного видео.

• get_long_youtube_analysis_result: получает результат завершённого фонового задания для длинного видео.

• cancel_long_youtube_analysis: отменяет фоновое задание для длинного видео.

• continue_long_video_analysis: задаёт уточняющие вопросы по предыдущей сессии длинного видео как требуемая задача MCP.

Подробные описания входных данных, стратегий и примеров см. в docs/tools.md.

Длинные видео

Для VOD и длинных видео сначала вызовите get_youtube_analyzer_capabilities.

Встроенные инструменты для длинных видео требуют выполнения задач MCP. Если ваш клиент поддерживает только синхронные вызовы инструментов с фиксированным таймаутом (например, 120 секунд), используйте рабочий процесс заданий совместимости: start_long_youtube_analysis, затем опрос get_long_youtube_analysis_status, затем получение get_long_youtube_analysis_result. Вы также можете анализировать более короткие ограниченные окна с помощью analyze_youtube_video.

Когда доступны yt-dlp, ffmpeg и каталог для временных файлов, используйте analyze_long_youtube_video со strategy=auto или strategy=uploaded_file. Этот путь позволяет создать переиспользуемую файловую сессию Gemini и вернуть sessionId.

Когда локальные инструменты загрузки недоступны, используйте strategy=url_chunks. Это позволяет избежать локальной загрузки медиа, но может потребовать больше вызовов Gemini.

Полное руководство см. в docs/long-videos.md.

Документация

• Установка

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

• Инструменты

• Длинные видео

• Примеры

• Устранение неполадок

• Процесс выпуска

• Журнал изменений

Конфиденциальность и ограничения

Этот сервер отправляет URL YouTube, запросы и соответствующие медиа или производные фрагменты в Google Gemini. При strategy=uploaded_file локальные инструменты могут загружать временные медиа перед отправкой в Gemini. get_youtube_video_frame загружает небольшое временное окно видео в высоком качестве и возвращает точный кадр JPEG; если запрошено уточнение временной метки, Gemini используется только для выбора временной метки, а не для создания пикселей изображения. При strategy=url_chunks сервер избегает локальной загрузки медиа, но может выполнять больше вызовов Gemini.

Частные, удалённые, ограниченные по возрасту, доступные только участникам, защищённые DRM или ограниченные по региону видео могут не обрабатываться в зависимости от доступа YouTube и Gemini. Пользователи несут ответственность за соблюдение условий использования YouTube, условий API Gemini, правил авторского права и местного законодательства.

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

• packages/video-analysis-core/src: переиспользуемое ядро анализа видео.

• src/server.ts: сервер MCP и регистрация инструментов.

• src/mcp-server-main.ts: точка входа транспорта stdio.

• src/platform-runtime: адаптеры среды выполнения, используемые сервером MCP.

• bin/youtube-video-analyzer-mcp.js: обёртка CLI и процесс настройки.

• src/test: набор тестов.

Участие

Участие приветствуется. Начните с CONTRIBUTING.md, запустите npm test перед внесением изменений и обновите CHANGELOG.md для изменений, заметных пользователям.

Лицензия

MIT. См. LICENSE.