Что это такое?

Video URL Analyzer MCP — это сервер протокола Model Context Protocol (MCP), который позволяет Claude (или любому другому AI, совместимому с MCP) анализировать видео с YouTube, TikTok и Instagram — просто вставьте URL. Работает на базе API Google Gemini с полноценным анализом аудио и видео, извлекает транскрипты, предоставляет AI-инсайты и даже может извлекать исполняемые шаги обучения.

Возможности

Анализ YouTube — Прямой анализ через Gemini API (скачивание не требуется)
TikTok и Instagram — Асинхронная обработка через скачивание yt-dlp + Gemini Files API
Полный анализ аудио + видео — Анализирует как кадры видео, так и аудио/речь
6 инструментов — analyze, transcript, Q&A, watch & analyze, execute tutorials, check jobs
Двуязычность — Поддержка запросов и ответов на арабском и английском языках
Асинхронные задачи — Фоновая обработка предотвращает зависания Claude Desktop из-за тайм-аутов
Усиленная безопасность — Белый список URL, защита от SSRF, предотвращение инъекций команд, блокировка обхода путей
Установка без настройки — uvx video-url-analyzer-mcp и всё готово к работе

Поддерживаемые платформы

Платформа	Метод	Скорость
YouTube	Прямой анализ Gemini — скачивание не нужно	Мгновенно
TikTok	API tikwm.com (быстро) → резервный yt-dlp	~8с
Instagram	Парсинг страницы через curl_cffi (быстро) → резервный yt-dlp	~10с

Видео с YouTube анализируются напрямую через встроенные возможности понимания видео Gemini — нулевое скачивание, нулевая загрузка, максимальная скорость.

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

Вариант 1: uvx (Рекомендуется)

Требуется uv.

Claude Desktop -- добавьте в claude_desktop_config.json:

{
  "mcpServers": {
    "video-analyzer": {
      "command": "uvx",
      "args": ["video-url-analyzer-mcp"],
      "env": {
        "GEMINI_API_KEY": "your_key"
      }
    }
  }
}

Claude Code:

claude mcp add video-analyzer -s user -e GEMINI_API_KEY=your_key -- uvx video-url-analyzer-mcp

Cursor / VS Code -- добавьте в .cursor/mcp.json или .vscode/mcp.json:

{
  "servers": {
    "video-analyzer": {
      "command": "uvx",
      "args": ["video-url-analyzer-mcp"],
      "env": { "GEMINI_API_KEY": "your_key" }
    }
  }
}

Windsurf -- добавьте в ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "video-analyzer": {
      "command": "uvx",
      "args": ["video-url-analyzer-mcp"],
      "env": { "GEMINI_API_KEY": "your_key" }
    }
  }
}

Вариант 2: pip install

pip install video-url-analyzer-mcp

Вариант 3: Из исходного кода

git clone https://github.com/u2n4/video-url-analyzer-mcp.git
cd video-url-analyzer-mcp
pip install -e .

Инструменты

Инструмент	Что он делает
`analyze_video`	Полный аудио-визуальный анализ с пользовательскими промптами. Использует Gemini для передового мультимодального понимания.
`get_transcript`	Извлечение транскрипта с временными метками и идентификацией спикеров. Поддерживает 100+ языков через автоопределение.
`ask_about_video`	Задайте любой вопрос — "Сколько людей в кадре?", "Какой бренд показан на 0:45?", "Обобщи основной аргумент."
`watch_and_analyze`	Извлечение шагов обучения, команд оболочки, фрагментов кода и путей к файлам из технических видео.
`execute_tutorial_steps`	Безопасный просмотр извлеченных шагов с последующим выполнением после подтверждения. Песочница с проверкой команд и путей.
`check_analysis_job`	Опрос статуса фоновой задачи для асинхронных загрузок TikTok/Instagram.

Как это работает

YouTube — Синхронно: URL отправляется напрямую в Gemini API для мгновенного анализа (без скачивания).

TikTok и Instagram — Асинхронно: Видео скачивается через yt-dlp, загружается в Gemini Files API, анализируется, а затем удаляется. Сразу возвращает job_id — опрашивайте статус через check_analysis_job.

Примеры использования

# Full video analysis
analyze_video("https://www.youtube.com/watch?v=dQw4w9WgXcQ")

# Custom analysis prompt
analyze_video("https://www.tiktok.com/@user/video/123",
              prompt="List every product shown and estimate prices")

# Multilingual transcript extraction
get_transcript("https://www.instagram.com/reel/ABC123/", lang="ar")

# Ask specific questions about video content
ask_about_video("https://youtu.be/abc",
                question="What programming language is used in the tutorial?")

# Watch & build — extract tutorial steps
watch_and_analyze("https://www.youtube.com/watch?v=tutorial123")

Архитектура

Компонент	Роль
Gemini API	Мультимодальная модель — полное аудио-визуальное понимание за один проход
FastMCP 3.x	Фреймворк протокола MCP поверх транспорта stdio
yt-dlp + curl_cffi	Скачивание видео с имитацией браузера Chrome для обхода анти-бот систем
API tikwm.com	Резервный быстрый путь для TikTok, если yt-dlp заблокирован WAF
Фоновые задачи	Асинхронная многопоточность для TikTok/Instagram для предотвращения тайм-аутов Claude Desktop

video-url-analyzer-mcp/
├── pyproject.toml                    # Package metadata & dependencies
├── src/
│   └── video_url_analyzer_mcp/
│       ├── __init__.py               # Package init + version
│       ├── __main__.py               # python -m support
│       └── server.py                 # Main MCP server (all 6 tools)
├── .env.example                      # Environment variable template
├── llms.txt                          # AI-readable project summary
├── llms-install.md                   # AI-readable install guide
├── CONTRIBUTING.md
├── CHANGELOG.md
└── LICENSE

Определение платформы

URL автоматически направляются в нужный конвейер:

YouTube: youtube.com, youtu.be, youtube.com/shorts/
TikTok: tiktok.com, vm.tiktok.com, vt.tiktok.com
Instagram: instagram.com/reels/, instagram.com/reel/, instagram.com/p/

Безопасность

Этот сервер был усилен против комплексной модели угроз:

Уровень	Защита
SSRF	Белый список URL — принимаются только домены YouTube, TikTok, Instagram. Частные IP, localhost, `file://` заблокированы.
Инъекция команд	`shell=False` + `shlex.split()`. Черный список опасных команд (rm -rf, обратные оболочки, eval, pipe-to-shell).
Обход путей	Заблокировано 25+ шаблонов чувствительных путей (`.ssh`, `.aws`, `.env`, системные директории, AppData).
TLS	Полная проверка сертификатов при всех загрузках.
Cookies браузера	Только по выбору через `VIDEO_ANALYZER_COOKIES=true`. По умолчанию отключено.
Размер загрузки	Жесткое ограничение 100 МБ на видео.
Защита от DoS	Максимум 10 одновременных фоновых задач. Автоматическое удаление через 1 час. Лимит хранилища 200 анализов.
Валидация схемы	JSON-ответы Gemini проверяются перед выполнением. Размер ответа ограничен 500 тыс. символов.
Зависимости	Все версии зафиксированы в `pyproject.toml`.

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

Переменная	Описание	По умолчанию
`GEMINI_API_KEY`	Ключ API Google Gemini (обязательно)	—
`ANALYSES_DIR`	Директория для хранения результатов анализа	`./analyses`
`VIDEO_ANALYZER_COOKIES`	Включить cookies браузера для yt-dlp	`false`

Технологический стек

Технология	Назначение
google-genai	SDK API Google Gemini
FastMCP	Фреймворк протокола MCP
yt-dlp	Загрузчик видео
curl_cffi	Имитация браузера (TLS fingerprint)
python-dotenv	Загрузка переменных окружения

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

Проблема	Решение
`GEMINI_API_KEY not set`	Создайте файл `.env` или передайте через переменную окружения
Ошибка загрузки TikTok	Резервный tikwm.com активируется автоматически. Убедитесь, что установлен `curl_cffi`.
Ошибка загрузки Instagram	`pip install curl_cffi` для поддержки имитации браузера
`ENOENT` на Windows	Используйте `uvx video-url-analyzer-mcp` в качестве команды
Тайм-аут Claude Desktop	TikTok/Instagram работают в фоне — используйте `check_analysis_job(job_id)` для опроса
Python не найден	Установите Python 3.10+ с python.org

Участие в разработке

См. CONTRIBUTING.md для руководств.

Лицензия

MIT — см. LICENSE.

Поддержка

Если вы находите это полезным, пожалуйста, поставьте звезду этому репозиторию!

Сделано с ❤️ в Восточной провинции Саудовской Аравии.

العربية

خادم تحليل الفيديو بالذكاء الاصطناعي

خادم MCP لتحليل الفيديو باستخدام Google Gemini — احدث واقوى نموذج ذكاء اصطناعي متعدد الوسائط من جوجل.

المميزات

الاداة	الوصف
`analyze_video`	تحليل شامل للصوت والصورة مع دعم الاوامر المخصصة
`get_transcript`	استخراج النص المنطوق مع الطوابع الزمنية — يدعم +100 لغة
`ask_about_video`	اسال اي سؤال عن محتوى الفيديو
`watch_and_analyze`	استخراج خطوات الشروحات التقنية والاوامر والاكواد
`execute_tutorial_steps`	مراجعة وتنفيذ الخطوات المستخرجة بامان

المنصات المدعومة

المنصة	السرعة
يوتيوب	فوري — تحليل مباشر بدون تحميل
تيك توك	~8 ثواني — واجهة tikwm.com السريعة
انستاجرام	~10 ثواني — استخراج مباشر من الصفحة

التثبيت السريع

git clone https://github.com/u2n4/video-url-analyzer-mcp.git
cd video-url-analyzer-mcp
pip install -e .

الامان

الخادم محمي ضد:

SSRF — قائمة بيضاء للنطاقات المسموحة فقط
حقن الاوامر — حظر الاوامر الخطيرة + تنفيذ بدون shell
اختراق المسارات — حظر 25+ مسار حساس
حماية من الحمل الزائد — حد اقصى 10 مهام متزامنة

الحصول على مفتاح API

اذهب الى Google AI Studio
انشئ مفتاح API مجاني
ضعه في ملف .env

video-url-analyzer-mcp