¿Qué es esto?

Video URL Analyzer MCP es un servidor del Protocolo de Contexto de Modelos (MCP) que permite a Claude (o cualquier IA compatible con MCP) analizar vídeos de YouTube, TikTok e Instagram; solo tienes que pegar una URL. Impulsado por la API Gemini de Google con análisis completo de audio y vídeo, extrae transcripciones, proporciona información basada en IA e incluso puede extraer pasos de tutoriales ejecutables.

Características

Análisis de YouTube — Análisis directo a través de la API Gemini (no requiere descarga)
TikTok e Instagram — Patrón de trabajo asíncrono con descarga mediante yt-dlp + API Gemini Files
Audio + Vídeo completo — Analiza tanto los fotogramas del vídeo como el audio/voz
6 herramientas — analyze, transcript, Q&A, watch & analyze, execute tutorials, check jobs
Bilingüe — Admite prompts y respuestas en árabe e inglés
Trabajos asíncronos — El procesamiento en segundo plano evita bloqueos por tiempo de espera en Claude Desktop
Seguridad reforzada — Lista blanca de URL, protección SSRF, prevención de inyección de comandos, bloqueo de recorrido de rutas
Instalación sin configuración — uvx video-url-analyzer-mcp y ya está funcionando

Plataformas compatibles

Plataforma	Método	Velocidad
YouTube	Análisis directo de Gemini: no requiere descarga	Instantáneo
TikTok	API tikwm.com (rápido) → alternativa yt-dlp	~8s
Instagram	Raspado de página mediante curl_cffi (rápido) → alternativa yt-dlp	~10s

Los vídeos de YouTube se analizan directamente a través de la comprensión de vídeo nativa de Gemini: cero descargas, cero subidas, máxima velocidad.

Inicio rápido

Opción 1: uvx (Recomendado)

Requiere uv.

Claude Desktop -- añadir a 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 -- añadir a .cursor/mcp.json o .vscode/mcp.json:

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

Windsurf -- añadir a ~/.codeium/windsurf/mcp_config.json:

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

Opción 2: pip install

pip install video-url-analyzer-mcp

Opción 3: Desde el código fuente

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

Herramientas

Herramienta	Qué hace
`analyze_video`	Análisis completo de audio y vídeo con prompts personalizados. Utiliza Gemini para una comprensión multimodal de vanguardia.
`get_transcript`	Extrae la transcripción con marcas de tiempo e identificación de hablantes. Admite más de 100 idiomas mediante detección automática.
`ask_about_video`	Haz cualquier pregunta: "¿Cuántas personas aparecen?", "¿Qué marca se muestra en el minuto 0:45?", "Resume el argumento principal".
`watch_and_analyze`	Extrae pasos de tutoriales, comandos de shell, fragmentos de código y rutas de archivos de vídeos técnicos.
`execute_tutorial_steps`	Revisa los pasos extraídos de forma segura y ejecútalos con confirmación. Aislado con validación de comandos y rutas.
`check_analysis_job`	Consulta el estado del trabajo en segundo plano para descargas asíncronas de TikTok/Instagram.

Cómo funciona

YouTube — Síncrono: la URL se envía directamente a la API Gemini para un análisis instantáneo (sin descarga).

TikTok e Instagram — Asíncrono: el vídeo se descarga mediante yt-dlp, se sube a la API Gemini Files, se analiza y luego se elimina. Devuelve un job_id inmediatamente; consulta el estado con check_analysis_job.

Ejemplos de uso

# 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")

Arquitectura

Componente	Rol
Gemini API	Modelo multimodal: comprensión completa de audio y vídeo en una sola pasada
FastMCP 3.x	Marco de protocolo MCP sobre transporte stdio
yt-dlp + curl_cffi	Descarga de vídeo con suplantación de navegador Chrome para evitar anti-bot
tikwm.com API	Ruta rápida alternativa para TikTok cuando yt-dlp está bloqueado por WAF
Trabajos en segundo plano	Hilos asíncronos para TikTok/Instagram para evitar tiempos de espera en 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

Detección de plataforma

Las URL se enrutan automáticamente a la canalización correcta:

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/

Seguridad

Este servidor ha sido reforzado contra un modelo de amenazas integral:

Capa	Protección
SSRF	Lista blanca de URL: solo se aceptan dominios de YouTube, TikTok e Instagram. IPs privadas, localhost y `file://` bloqueados.
Inyección de comandos	`shell=False` + `shlex.split()`. Lista negra de comandos peligrosos (rm -rf, reverse shells, eval, pipe-to-shell).
Recorrido de rutas	Más de 25 patrones de rutas sensibles bloqueados (`.ssh`, `.aws`, `.env`, directorios del sistema, AppData).
TLS	Validación completa de certificados en todas las descargas.
Cookies del navegador	Solo bajo consentimiento mediante `VIDEO_ANALYZER_COOKIES=true`. Desactivado por defecto.
Tamaño de descarga	Límite estricto de 100 MB por vídeo.
Protección DoS	Máximo de 10 trabajos en segundo plano simultáneos. Expiración automática después de 1 hora. Límite de almacenamiento de 200 análisis.
Validación de esquema	Respuestas JSON de Gemini validadas antes de la ejecución. Tamaño de respuesta limitado a 500 mil caracteres.
Dependencias	Todas las versiones fijadas en `pyproject.toml`.

Configuración

Variable	Descripción	Por defecto
`GEMINI_API_KEY`	Clave de API de Google Gemini (obligatorio)	—
`ANALYSES_DIR`	Directorio para almacenar los resultados del análisis	`./analyses`
`VIDEO_ANALYZER_COOKIES`	Habilitar cookies del navegador para yt-dlp	`false`

Stack tecnológico

Tecnología	Propósito
google-genai	SDK de la API de Google Gemini
FastMCP	Marco de protocolo MCP
yt-dlp	Descargador de vídeos
curl_cffi	Suplantación de navegador (huella digital TLS)
python-dotenv	Carga de variables de entorno

Solución de problemas

Problema	Solución
`GEMINI_API_KEY not set`	Crea un archivo `.env` o pásala mediante una variable de entorno
La descarga de TikTok falla	La alternativa tikwm.com se activa automáticamente. Asegúrate de que `curl_cffi` esté instalado.
La descarga de Instagram falla	`pip install curl_cffi` para soporte de suplantación de navegador
`ENOENT` en Windows	Usa `uvx video-url-analyzer-mcp` como comando
Tiempo de espera de Claude Desktop	TikTok/Instagram se ejecutan en segundo plano; usa `check_analysis_job(job_id)` para consultar
Python no encontrado	Instala Python 3.10+ desde python.org

Contribución

Consulta CONTRIBUTING.md para ver las directrices.

Licencia

MIT: consulta LICENSE.

Soporte

Si te resulta útil, ¡por favor dale una estrella a este repositorio!

Hecho con ❤️ en la Provincia Oriental de Arabia Saudita.

العربية

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

خادم 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