mcp-video-analyzer

mcp-video-analyzer

Transforme qualquer vídeo — YouTube, Instagram, TikTok, Loom, X, Vimeo, links diretos, arquivos locais — em transcrições, quadros-chave, texto OCR e metadados para agentes de IA.

Nenhum MCP de vídeo existente combina transcrições + quadros visuais + metadados em uma única ferramenta. Este combina — em Loom, nas principais plataformas yt-dlp (YouTube/Vimeo/TikTok/Instagram/X/Twitch/Dailymotion/Facebook), URLs de vídeo diretos e arquivos locais.

Quer um pipeline completo, não apenas uma ferramenta? social-knowledge-base é construído sobre este servidor — ele baixa contas inteiras de criadores do Instagram (reels, stories, destaques), transcreve-as e transforma o resultado em uma base de conhecimento pesquisável e consultável via RAG, com notas geradas por IA. Use este MCP quando quiser análise por vídeo dentro de um agente; use social-knowledge-base quando quiser arquivar e consultar uma conta inteira.

Instalação

Pré-requisitos

• Node.js 22.12+ — necessário para executar o servidor via npx
• yt-dlp — obrigatório para URLs do YouTube/Vimeo/TikTok/Instagram/X/Twitch/Dailymotion/Facebook; opcional para todo o resto (melhora a qualidade do download do Loom). Instale com pip install yt-dlp
• Chrome/Chromium (opcional) — alternativa para extração de quadros se o yt-dlp não estiver disponível

Sem yt-dlp ou Chrome, URLs diretos e arquivos locais ainda geram quadros — o ffmpeg-static incluído faz a extração, e o Loom usa o download do próprio CDN como alternativa. URLs de plataformas (YouTube etc.) degradam para um aviso claro de "instale o yt-dlp". Transcrições, metadados e comentários nunca exigem nenhum dos dois.

Há três formas de acesso: o plugin /video (Claude Code — comando de barra + servidor MCP configurado automaticamente), uma configuração MCP server simples (qualquer cliente MCP) ou a skill portátil + CLI (Codex, Cursor, Copilot e qualquer agente com shell — sem necessidade de MCP).

Claude Code — plugin /video (recomendado)

/plugin marketplace add guimatheus92/mcp-video-analyzer
/plugin install video@mcp-video-analyzer

Isso adiciona o comando de barra /video e registra automaticamente o servidor MCP — sem necessidade de claude mcp add:

/video https://youtu.be/jNQXAC9IVRw what happens at 0:10?
/video ~/Movies/screen-recording.mp4 when does the UI break?

Outros agentes — Codex, Cursor, Copilot, Gemini CLI, …

npx skills add guimatheus92/mcp-video-analyzer

Instala a skill video (formato Agent Skills) em todos os agentes detectados na sua máquina. Agentes sem o servidor MCP configurado usam automaticamente a CLI incluída — zero configuração.

Claude Code (somente MCP)

claude mcp add video-analyzer -- npx mcp-video-analyzer@latest

Depois reinicie o Claude Code ou inicie uma nova conversa.

VS Code / Cursor

Adicione ao seu arquivo de configurações MCP:

• VS Code: File → Preferences → Settings → search "MCP" ou edite ~/.vscode/mcp.json / %APPDATA%\Code\User\mcp.json (Windows)
• Cursor: Settings → MCP Servers → Add

{
  "servers": {
    "mcp-video-analyzer": {
      "type": "stdio",
      "command": "npx",
      "args": ["mcp-video-analyzer@latest"]
    }
  }
}

Depois recarregue a janela (Ctrl+Shift+P → "Developer: Reload Window").

Claude Desktop

Adicione ao arquivo de configuração do Claude Desktop:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "video-analyzer": {
      "command": "npx",
      "args": ["mcp-video-analyzer@latest"]
    }
  }
}

Depois reinicie o Claude Desktop.

CLI (uso único, sem cliente MCP)

O mesmo mecanismo é exposto como um comando de uso único — é isso que a skill video usa em agentes sem MCP, e funciona de forma independente em qualquer terminal:

npx -y mcp-video-analyzer@latest analyze "https://youtu.be/jNQXAC9IVRw"

O stdout é um único documento JSON — metadata, transcript, ocrResults, timeline, warnings, frameCount e frames como entradas { time, filePath, mimeType } apontando para quadros-chave JPEG copiados para --out (padrão: o diretório de cache por usuário — %LOCALAPPDATA% no Windows, ~/Library/Caches no macOS, $XDG_CACHE_HOME ou ~/.cache no Linux — em mcp-video-analyzer/<url-hash>/; defina MCP_CACHE_DIR para um caminho absoluto para realocá-lo). Diferente do diretório temporário onde costumava ficar, nada remove esse local, então os quadros persistem até você excluí-los — os diretórios são criados 0700. O progresso é transmitido no stderr, então stdout pode ser canalizado diretamente para um analisador JSON. Falhas parciais ficam em warnings com código de saída 0; apenas falhas graves saem com código 1.

Execute sem argumentos (npx mcp-video-analyzer@latest) para iniciar o servidor MCP stdio — a CLI é puramente aditiva.

Verifique se funciona

Após a instalação, pergunte ao seu assistente de IA:

Analyze this video: https://www.youtube.com/watch?v=jNQXAC9IVRw

(também funciona com um link do Instagram/TikTok/Loom, uma URL .mp4 direta ou um caminho de arquivo local). Se o servidor estiver conectado, ele chamará automaticamente a ferramenta analyze_video.

Ferramentas

Oito ferramentas — a IA escolhe a mais barata para a tarefa e a chama automaticamente. Clique em qualquer ferramenta para expandir seus parâmetros e exemplos.

> Analyze this video: https://www.youtube.com/watch?v=abc123...

> Analyze every .mp4 in this folder

> Get the transcript from this video

> What's this video about?

> Extract frames from this video with dense sampling

> Analyze what happens between 1:30 and 2:00 in this video

> Show me the frame at 1:23 in this video

> Show me 10 frames between 0:15 and 0:17 of this video

Níveis de Detalhe

Cache

Os resultados são armazenados em cache na memória por 10 minutos. Chamadas subsequentes com a mesma URL e opções retornam instantaneamente. Use forceRefresh: true para ignorar o cache. skipFrames faz parte do cache e da chave do sidecar, então uma análise apenas de transcrição e uma com quadros da mesma URL nunca respondem uma pela outra.

Sidecars persistentes (processamento em lote retomável)

O cache em memória é perdido ao reiniciar, o que torna o reprocessamento de um grande corpus local custoso. Defina MCP_WRITE_SIDECARS=1 para também persistir resultados ao lado de cada vídeo local para que o trabalho sobreviva a reinicializações e possa ser retomado:

• <stem>.vtt — a transcrição, somente quando foi gerada pelo fallback Whisper (um <stem>.vtt existente do seu próprio pipeline nunca é sobrescrito). Uma chamada posterior o reutiliza via leitor de sidecar normal e ignora o Whisper completamente.
• <stem>.analysis.json + <stem>.frames/ — o resultado completo (quadros + OCR + linha do tempo), chaveado pelo mtime:size do vídeo e pelos parâmetros de análise. Em uma chamada posterior com carimbo + parâmetros correspondentes, o resultado é retornado diretamente do disco (sem extração, sem OCR).

Isso torna o analyze_videos sobre milhares de arquivos retomável, e permite que um pipeline externo de transcrição por GPU e este MCP compartilhem resultados através do sistema de arquivos: o pipeline escreve <stem>.vtt, e o MCP o utiliza em vez de executar o Whisper.

Fontes Suportadas

Quadros Loom: transcrição, metadados e comentários vêm diretamente da API do Loom sem ferramentas extras. A extração de quadros é diferente — o Loom serve a maioria dos vídeos como streams DASH separados de vídeo+áudio, que apenas yt-dlp (pip install yt-dlp) busca e mescla. A mesclagem usa o ffmpeg-static incluído, então nenhum ffmpeg do sistema é necessário. Sem yt-dlp, um fallback de CDN direto ainda cobre alguns vídeos; quando não consegue, você recebe transcrição + metadados + comentários além de um aviso explicando por que os quadros estão ausentes.

Arquivos locais: passe um caminho absoluto (ex.: /Users/you/clip.mp4) ou uma URI file:// como argumento url para qualquer ferramenta. Caminhos relativos são rejeitados — o diretório de trabalho do servidor é imprevisível a partir do cliente MCP. Observe que qualquer chamador do servidor MCP pode pedir que ele leia qualquer arquivo ao qual o processo do servidor tenha acesso.

Transcrições sidecar: se um clip.vtt, clip.srt, clip.en.vtt, etc. estiver ao lado de clip.mp4, ele é usado como transcrição automaticamente — sem ida e volta ao Whisper. SRT é convertido para VTT em memória.

Legendas incorporadas: se nenhum sidecar for encontrado e o contêiner tiver um stream de legenda incorporado (comum em .mkv / .mov / .mp4 de gravadores de tela), ele é transmuxado para VTT via ffmpeg e usado como transcrição.

Extensões reconhecidas (arquivos locais e URLs diretas): .mp4 .mov .mkv .webm .avi .m4v .wmv .flv .mpeg .mpg .m2ts .mts .3gp .ogv. A extensão apenas controla o roteamento — o ffmpeg faz a demuxagem real, então a maioria dos contêineres comuns funciona. .ts é excluído para evitar colisão com arquivos-fonte TypeScript.

URLs de plataformas via yt-dlp (YouTube, Instagram, TikTok, …)

Páginas de vídeo único em grandes plataformas passam por yt-dlp (pip install yt-dlp — necessário para essas URLs). Playlists, canais e páginas de perfil são rejeitados por design; passe URLs de vídeo individuais (agrupe-as com analyze_videos).

• Transcrição: legendas nativas são preferidas e gratuitas — legendas enviadas primeiro, legendas geradas automaticamente como fallback (duplicação de janela deslizante é colapsada). WHISPER_LANGUAGE (ex.: pt) também é usado para escolher o idioma da legenda. Vídeos sem legendas caem na cadeia normal do Whisper.
• Metadados: título, duração, uploader/canal, contagem de visualizações, data de upload e capítulos — sem necessidade de download.
• Download: limitado a 1080p (quadros/OCR não precisam de mais), streams ao vivo são ignorados, e DASH áudio+vídeo é mesclado com o ffmpeg-static incluído (nenhum ffmpeg do sistema necessário).
• Cookies — Instagram e vídeos restritos por idade geralmente exigem uma sessão logada:

A extração de cookies do navegador exige que o navegador esteja fechado no Windows (o banco de dados de cookies fica bloqueado enquanto ele está em execução). Se isso for inconveniente, exporte um cookies.txt uma vez (ex.: com uma extensão de navegador "Get cookies.txt") e aponte YTDLP_COOKIES para ele. Vídeos privados/restritos por idade sem cookies válidos não travam a ferramenta — a linha ERROR: do yt-dlp aparece em warnings[].

TwelveLabs Pegasus (opcional)

Defina a variável de ambiente TWELVELABS_API_KEY para analisar URLs de vídeo diretas com TwelveLabs Pegasus. O Pegasus analisa o vídeo no lado do servidor (visuais e seu próprio áudio) e retorna uma transcrição com carimbo de tempo gerada por IA além de um resumo de IA como texto — capacidades que o DirectAdapter não pode fornecer (uma URL .mp4 bruta não tem transcrição ou resumo por conta própria), e sem necessidade de chave Whisper.

A transcrição é saída de LLM de melhor esforço, não um despejo ASR determinístico: o Pegasus é instruído a emitir linhas [MM:SS] line, e linhas que não correspondem a esse formato são descartadas, então a redação e os carimbos de tempo exatos dependem da adesão do modelo às instruções. Falhas (chave inválida, timeout, erro de API) aparecem no warnings[] da ferramenta em vez de retornar silenciosamente uma transcrição vazia.

A maior vantagem está nos caminhos somente texto: get_transcript e get_metadata retornam uma transcrição e resumo Pegasus para URLs diretas — alguns KB de texto, sem imagens de quadros, sem custo de token por quadro. analyze_video em detail: "standard"/"detailed" ainda extrai quadros adicionalmente (use detail: "brief" para permanecer somente texto).

Vídeos longos: o resumo e a transcrição completa compartilham uma única conclusão limitada (max_tokens = 16384), então para vídeos muito longos a transcrição pode ser truncada. Para conteúdo de várias horas, dividir por janela de tempo é a abordagem melhor.

É totalmente opt-in e não quebra nada: quando TWELVELABS_API_KEY está definido, o TwelveLabsAdapter lida com URLs de vídeo diretas (ele registra a URL pública com TwelveLabs — sem upload); quando não está definido, o DirectAdapter lida com elas exatamente como antes. URLs do Loom não são afetadas. Obtenha uma chave em playground.twelvelabs.io.

Transcrição (fallback Whisper)

Quando uma fonte não tem transcrição nativa (sem sidecar .vtt/.srt, sem legendas incorporadas, sem legendas de plataforma), a faixa de áudio é transcrita com Whisper via uma cadeia de fallback graciosa (em ordem de execução):

Faixas silenciosas: antes de qualquer execução do Whisper, o áudio é sondado com ffmpeg volumedetect (primeiros 2 minutos). Uma faixa presente mas muda — comum em Reels/Stories silenciados — pula a transcrição completamente e emite um aviso de que a transcrição vazia é conteúdo esperado, não um erro, economizando uma execução inútil do Whisper.

1. @huggingface/transformers (JS-nativo, zero dependências externas) — somente opt-in: esta estratégia é executada primeiro, mas apenas quando WHISPER_HF_MODEL está explicitamente definido. Quando não está definido (o padrão), a estratégia é completamente ignorada, então o CLI abaixo vence e suas configurações WHISPER_MODEL/WHISPER_LANGUAGE nunca são silenciosamente sobrescritas.
2. CLI whisper — usado quando um executável whisper é encontrado (pip install -U openai-whisper). Aponte WHISPER_BIN para o executável se ele não estiver em PATH. Modelo via WHISPER_MODEL, idioma via WHISPER_LANGUAGE. O ffmpeg-static incluído é colocado no PATH do CLI automaticamente, então nenhum ffmpeg do sistema é necessário.
3. OpenAI Whisper API — usado quando OPENAI_API_KEY está definido.

Nenhum backend configurado? Se nenhum dos três estiver disponível (sem whisper em PATH/WHISPER_BIN, sem OPENAI_API_KEY, sem WHISPER_HF_MODEL), as ferramentas de transcrição retornam uma transcrição vazia com um aviso dizendo como habilitar uma — em vez de um "sem transcrição" silencioso. Instale openai-whisper ou defina uma das chaves acima. (O CLI é iniciado com PYTHONUTF8=1 para que transcrições não-inglesas/CJK não travem o processo Python no Windows.)

O modelo tiny padrão é rápido, mas fraco para áudio não-inglês. Para fontes em português (ou outros idiomas não-inglês), instale a CLI e defina WHISPER_MODEL=small (ou medium) + WHISPER_LANGUAGE=pt para uma precisão muito melhor. Adicione WHISPER_PROMPT com um glossário de domínio (nomes de marcas/lugares) para corrigir nomes próprios. Você também pode substituir model/language/initialPrompt por chamada em analyze_video / get_transcript / analyze_videos — sem necessidade de reiniciar.

GPU (faster-whisper): whisper-ctranslate2 (pip install -U whisper-ctranslate2) é uma CLI substituta com os mesmos flags, além de --device cuda / --compute_type / --beam_size. Aponte WHISPER_BIN para ela e defina WHISPER_DEVICE=cuda (+ opcionalmente WHISPER_COMPUTE=float16). Esses flags de GPU são controlados por variáveis de ambiente — eles só são passados quando definidos, então o openai-whisper simples (que rejeita --compute_type) continua funcionando quando eles não estão definidos.

Nota para Windows: o pip instala whisper.exe no diretório Scripts/ do Python, que muitas vezes não está no PATH que clientes MCP iniciados por GUI herdam. Se as transcrições voltarem vazias, defina WHISPER_BIN para o caminho completo de whisper.exe.

Estratégias de Extração de Quadros

A extração de quadros usa uma cadeia de fallback de duas estratégias — nenhuma dependência única é obrigatória:

O fallback é automático — se o yt-dlp não estiver disponível, o servidor tenta a extração via navegador usando puppeteer-core. Se nenhum estiver disponível, a análise ainda retorna transcrição + metadados + comentários, apenas sem quadros.

Pipeline de Pós-Processamento

Após a extração de quadros, o pipeline aplica automaticamente:

A etapa de OCR requer tesseract.js (incluído como dependência). Se falhar ao carregar, a análise continua sem OCR — nenhum quadro ou transcrição é perdido. O pré-processamento de OCR está ativado por padrão; defina MCP_OCR_PREPROCESS=0 para aplicar OCR nos quadros brutos.

O OCR sempre lê o quadro em resolução total, não a cópia enviada ao cliente. Os dois têm funções diferentes: o quadro enviado é limitado para custo de tokens, enquanto o reconhecimento precisa de cada pixel que puder obter.

Tamanho do quadro (capturas de UI densas)

Os quadros enviados são limitados a 800 px de largura, o que atende ao caso comum — clipes com pessoa falando, Reels, reprodução de bugs — onde o assunto preenche o quadro.

É o tamanho errado para uma captura de UI densa: uma gravação de terminal, dashboard, IDE ou planilha, onde o significado está em texto pequeno. Uma gravação de tela 1920×1080 sem redimensionamento chega a 800×450, e uma fonte de UI de 15 px cai abaixo do que um modelo de visão consegue resolver.

Passe maxWidth por chamada para manter mais (ou toda) a resolução da fonte — 0 desativa o limite:

get_frames(url, { maxFrames: 8, maxWidth: 0 })   // source resolution
get_frame_at(url, "2:14", { maxWidth: 1920 })
analyze_video(url, { detail: "standard", maxWidth: 1568 })

Suportado em analyze_video, analyze_videos, analyze_moment, get_frames, get_frame_at e get_frame_burst, e na CLI como --max-width <px>.

Quadros nativos custam várias vezes mais contexto do que o padrão, então aumente o limite deliberadamente — get_frames retorna até 20 quadros e analyze_video em detailed até 60.

Um valor que qualquer variável não possa usar — 1e3, 1920px, uma qualidade de 150 — é rejeitado com um aviso único no stderr e o padrão é aplicado. Não é aceito silenciosamente: o objetivo do ajuste é escapar de um downscale que, de outra forma, parece um resultado normal.

Prefira o parâmetro por chamada: o servidor inicia uma vez por sessão, então uma variável de ambiente não pode diferir entre uma visão geral de um clipe do YouTube e uma leitura detalhada de uma gravação de tela. A largura que uma chamada realmente usa faz parte da chave de cache e sidecar, então analisar o mesmo vídeo a 800 px e depois a maxWidth: 0 reexecuta o pipeline em vez de retornar o primeiro resultado duas vezes.

Ferramentas Complementares

Chrome DevTools MCP

Para depuração web ao vivo junto com a análise de vídeo, combine este servidor com o Chrome DevTools MCP:

claude mcp add chrome-devtools npx @anthropic-ai/mcp-devtools@latest

Quando usar cada um:

Os dois MCPs se complementam: o analisador de vídeo entende conteúdo gravado, o DevTools interage com páginas ao vivo.

Exemplo de Saída

A pasta examples/loom-demo/ contém saídas reais da análise de um vídeo Loom público (Boost In-App Demo Video, 2:55).

Imagens dos quadros (19 no total em examples/loom-demo/frames/):

• scene_*.jpg — detecção de mudança de cena (transições visuais principais)
• dense_*.jpg — amostragem densa a 1fps (a cada 10º quadro salvo como amostra)
• burst_*.jpg — extração em rajada para análise de momento (0:30–0:45)

Regenerar após alterações: npx tsx examples/generate.ts — requer yt-dlp + acesso à rede.

Desenvolvimento

# Install dependencies
npm install

# Run all checks (format, lint, typecheck, knip, tests)
npm run check

# Audit dependencies. `security` covers what the published package ships and
# is a blocking CI job; `security:all` adds devDependencies. Both also run on
# a weekly cron, because npm audit reads a live advisory database.
npm run security

# Build
npm run build

# Run E2E tests (requires network; add WHISPER_E2E=1 to include the
# transcription outcome test — needs a whisper CLI installed)
npm run test:e2e

# Just the video-format matrix: a real clip per container/codec
# (mp4/h264+hevc+av1, webm, mkv, mov, avi, m4v, mpeg, mpg, m2ts, mts,
# 3gp, ogv, flv, wmv) decoded end to end. ~15s on a warm cache; the
# first run fetches ~7MB of tesseract traineddata.
npm run test:formats

# Build + boot the real MCP server/CLI (seconds)
npm run test:smoke

# Everything: check → e2e → smoke → verify-package
npm run verify-all

# Open MCP Inspector for manual testing
npm run inspect

Arquitetura

src/
├── index.ts                    # Entry point (shebang + stdio)
├── server.ts                   # FastMCP server + tool registration
├── tools/                      # MCP tool definitions (7 tools)
│   ├── analyze-video.ts        # Full analysis with detail levels + caching
│   ├── analyze-moment.ts       # Deep-dive on a time range
│   ├── get-transcript.ts       # Transcript-only with Whisper fallback
│   ├── get-metadata.ts         # Metadata + comments + chapters
│   ├── get-frames.ts           # Frames-only (scene-change or dense)
│   ├── get-frame-at.ts         # Single frame at timestamp
│   └── get-frame-burst.ts      # N frames in a time range
├── adapters/                   # Source-specific logic
│   ├── adapter.interface.ts    # IVideoAdapter interface + registry
│   ├── loom.adapter.ts         # Loom: authless GraphQL
│   ├── local-file.adapter.ts   # Local files: absolute path or file:// URI
│   ├── twelvelabs.adapter.ts   # TwelveLabs Pegasus: transcript + AI summary (opt-in)
│   └── direct.adapter.ts       # Direct URL: any mp4/webm link
├── processors/                 # Shared processing
│   ├── frame-extractor.ts      # ffmpeg scene detection + dense + burst extraction
│   ├── browser-frame-extractor.ts # Headless Chrome fallback for frames
│   ├── audio-transcriber.ts    # Whisper fallback (HF transformers → CLI → OpenAI)
│   ├── image-optimizer.ts      # sharp resize/compress
│   ├── frame-dedup.ts          # Perceptual dedup (dHash + Hamming distance)
│   ├── frame-ocr.ts            # OCR text extraction (tesseract.js)
│   └── annotated-timeline.ts   # Unified timeline (transcript + frames + OCR)
├── config/
│   └── detail-levels.ts        # brief / standard / detailed config
├── utils/
│   ├── cache.ts                # In-memory TTL cache with LRU eviction
│   ├── field-filter.ts         # Selective field filtering for responses
│   ├── url-detector.ts         # Platform detection from URL
│   ├── vtt-parser.ts           # WebVTT → transcript entries
│   └── temp-files.ts           # Temp directory management
└── types.ts                    # Shared TypeScript interfaces

Licença

MIT