Video URL Analyzer

io.github.u2n4Published by GitHub account u2n4v1.5.1Updated Oct 24, 2026

Analyze YouTube/TikTok/Instagram videos: transcripts, AI insights, tutorial extraction

VerifiedSTDIODesktop onlyWeb Search & Scraping Media & Design AI & ML

Server details

Identifier: io.github.u2n4/video-url-analyzer-mcp
Transport: STDIO
Runtime: Desktop only
Trust: Verified
Published: Sep 16, 2026

Security note

MCP servers receive tool arguments from a conversation and may perform external actions. Review what a server can do before you enable it, and give it only the access it needs.

The registry verified the GitHub account u2n4 for this listing. That does not show the account is the product's maker.

SourceWeft's checks cover whether the listing is complete and the endpoint answered; they do not review the server's code or what its tools do.

Add a badge to your README

Show readers this MCP server is listed on SourceWeft. The badge links to this page.

[![Listed on SourceWeft](https://sourceweft.com/badge/mcp/io.github.u2n4%2Fvideo-url-analyzer-mcp.svg)](https://sourceweft.com/mcp/io.github.u2n4%2Fvideo-url-analyzer-mcp?utm_source=readme&utm_medium=badge)

Overview

AI-generated overview

Local MCP server that lets an assistant analyze YouTube, TikTok and Instagram videos with Google Gemini: transcripts, Q&A, frames, clips and tutorial steps.

What you can do: Analyze videos and segments with custom prompts, or ask questions about their content using Gemini multimodal understanding, including photo and carousel posts on TikTok and Instagram. Extract timestamped, speaker-labeled transcripts in over 100 languages. Save a reusable local context per video, then answer follow-up questions from it, list or delete saved contexts, and inspect cache metadata. Extract still frames and short clips as local evidence assets, and clean up cached files with a dry-run default. Pull tutorial steps, shell commands, code snippets and file paths from technical videos, review them, and execute only with confirmation. Poll background job status for longer TikTok and 8s
When to use it: Useful when you want an assistant to summarize, question or mine a specific YouTube, TikTok or Instagram video without downloading it first, or to turn a technical tutorial video into reviewable steps. Best for research, content review and learning from video, not for bulk crawling.
Requirements: Runs locally over stdio, installed from PyPI with uvx or pip (Python 3.10+). Requires a Google Gemini API key in the GEMINI_API_KEY environment variable. ffmpeg and yt-dlp are used for frame and clip extraction; curl_cffi helps with TikTok and Instagram downloads. Network access to the video platforms and Google is needed.

Before you install

Requires a paid or free-tier Gemini API key (GEMINI_API_KEY); usage counts against your Google quota. The server downloads media from YouTube, TikTok and Instagram and sends it to Google Gemini for analysis, so video content leaves your machine. Optional browser cookie access (VIDEO_ANALYZER_COOKIES) is off by default; enabling it exposes session cookies. One tool can execute extracted tutorial steps, though only after confirmation. Delete and cleanup tools remove saved local contexts and cache.

Installation

In SourceWeft

Open Video URL Analyzer in the dashboard and add it to a workspace.
Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

[Video Analyzer MCP Server]

Video Analyzer MCP Server

Analyze any video with AI — YouTube, TikTok & Instagram
Powered by Google Gemini 3.5 Flash · FastMCP · yt-dlp

[Gemini 3.5 Flash] [Python 3.10+] [MCP stdio] [Security Hardened] [MIT License]

Features · Architecture · Quick Start · Integration · Security · العربية

Features

[Features — Analyze, Transcript, Ask]

v1.5.4 exposes 18 MCP tools:

Tool	What it does
`analyze_video`	Full audio + visual analysis with custom prompts. Uses Gemini multimodal understanding.
`get_transcript`	Extract timestamped transcript with speaker identification. Supports 100+ languages via auto-detection.
`ask_about_video`	Ask any question about the video content.
`prepare_slideshow_assets`	Return ordered slideshow images as MCP image blocks so Claude/the client AI can inspect them directly.
`find_video_moments`	Find matching moments with compact/standard/full structured output.
`analyze_video_segment`	Analyze only a selected time range.
`prepare_video_context`	Analyze once and save a reusable local context for follow-up questions and evidence lookup.
`ask_video_context`	Answer from saved context by default; Gemini reanalysis is explicit opt-in.
`list_video_contexts`	List saved local contexts.
`delete_video_context`	Delete one saved context.
`get_video_frame`	Extract a local still frame, using the YouTube fast path when possible.
`get_video_clip`	Extract a short local clip, with a 30s cap and YouTube fast path when possible.
`get_video_evidence_asset`	Select saved evidence and return a frame or clip reference.
`list_video_sources`	Inspect local source/context/asset cache metadata.
`cleanup_video_cache`	Dry-run or clean managed cache files; dry-run is the default.
`watch_and_analyze`	Extract tutorial steps, shell commands, code snippets, and file paths from technical videos.
`execute_tutorial_steps`	Validate and review extracted steps safely; executes only with confirmation.
`check_analysis_job`	Poll background job status for TikTok/Instagram async downloads.

Supported Platforms

Platform	Method	Speed
YouTube	Direct Gemini analysis — no download needed for analysis. Frame/clip extraction uses `yt-dlp -g` stream URLs + ffmpeg when available, with a small section-download fallback.	Instant / fast local extraction
TikTok	tikwm.com API (fast) → yt-dlp fallback with a safe MP4 H.264/H.265 selector that avoids unsupported ByteDance `bvc2`/`bytevc2` streams when possible	~8s
Instagram	Page scrape via curl_cffi (fast) → yt-dlp fallback	~10s

Photo / Slideshow Posts

Platform	Post type	Handling
TikTok	Photo Mode slideshow	Downloads all images, extracts the music/audio track when available, and sends one multimodal Gemini request.
Instagram	Carousel / single-photo posts	Downloads image slides in order and analyzes them as one post; mixed video slides are skipped with metadata.
YouTube	Community `/post/` image attachments	Scrapes `ytInitialData`, downloads image attachments, and analyzes them through Gemini Files API.

YouTube videos are analyzed directly through Gemini's native video understanding — zero download, zero upload, maximum speed. For YouTube evidence assets, source.mp4 is not always required: saved contexts keep the original URL, so frame/clip tools can use the local stream fast path later.

Architecture

[Architecture Diagram]

Component	Role
Gemini 3.5 Flash	Latest Gemini Flash model — full audio + visual understanding in a single pass
FastMCP 3.x	MCP protocol framework over stdio transport
yt-dlp + curl_cffi	Video download with Chrome browser impersonation to bypass anti-bot. TikTok downloads prefer locally decodable MP4 H.264/H.265 formats and reject ByteDance `bvc2`/`bytevc2` streams.
tikwm.com API	TikTok fast-path fallback when yt-dlp is WAF-blocked
ffmpeg	Local frame/clip extraction, including YouTube stream URL extraction without full-video downloads
Background Jobs	Async threading for TikTok/Instagram to prevent Claude Desktop timeouts. Failed inner results are reported as failed jobs, not completed jobs.

Operating Modes

These are behavior modes, not tool names:

Mode	Behavior
`auto`	Default adaptive behavior: YouTube direct analysis; TikTok/Instagram fast API/scrape then yt-dlp fallback; saved contexts reused when available.
`api`	Gemini-backed analysis or reanalysis. This is used by analysis tools and explicit Gemini opt-ins.
`client`	MCP client workflow mode: long TikTok/Instagram analysis returns a background `job_id` for polling.
`local`	Saved-context, cache, frame, and clip operations that avoid Gemini unless explicitly requested.

Quick Start

The packaged runtime lives at src/video_url_analyzer_mcp/server.py; the console entry point is video_url_analyzer_mcp:main. Pick whichever install path matches your workflow.

Option A — one-line Windows installer (recommended for new users)

The installer follows the current MCP client pattern: it installs/runs from PyPI with uvx, uses an existing GEMINI_API_KEY environment variable when one is already set, otherwise asks for the key only through a hidden prompt, and lets the user choose where to register the server:

Claude Code
Claude Desktop
Codex CLI
Cursor
Windsurf
VS Code / GitHub Copilot
Google Antigravity
Cline

Do not append your API key to the PowerShell command. If you skip the key, the installer still registers the server and you can set GEMINI_API_KEY later. If GEMINI_API_KEY is already set in your User environment, the installer will use it directly and print only a masked form like AIza...abcd.

Option B — `uvx` (no install)

Works on Windows / macOS / Linux as long as uv is on PATH.

Option C — Windows wizard from a checkout

powershell

git clone https://github.com/u2n4/video-url-analyzer-mcp.gitcd video-url-analyzer-mcppowershell -ExecutionPolicy Bypass -File scripts\install_windows.ps1

git clone https://github.com/u2n4/video-url-analyzer-mcp.gitcd video-url-analyzer-mcppowershell -ExecutionPolicy Bypass -File scripts\install_windows.ps1

The wizard:

Verifies Python 3.10+ and (optionally) uv.
Installs the package as an editable checkout or via uv tool install.
Lets you save GEMINI_API_KEY to a User environment variable or to a gitignored .env.keys.local. Keys are masked in logs (AIza...abcd), never printed in full.
Lets you pick a default model via VIDEO_ANALYZER_MODEL.
Runs an offline import smoke test.
Hands off to scripts/configure_mcp_clients.ps1 for client setup.

Option D — Manual install (any OS)

bash

git clone https://github.com/u2n4/video-url-analyzer-mcp.gitcd video-url-analyzer-mcppip install -e .python -m video_url_analyzer_mcp

git clone https://github.com/u2n4/video-url-analyzer-mcp.gitcd video-url-analyzer-mcppip install -e .python -m video_url_analyzer_mcp

Get a free key at Google AI Studio, then set it once in your shell environment (setx GEMINI_API_KEY ... on Windows, or your ~/.zshrc / ~/.bashrc on macOS/Linux). For local dev only, you can also drop it in a gitignored .env.keys.local next to the repo.

Windows launcher

start.bat loads .env.keys.local (if present), sets safe defaults (VIDEO_ANALYZER_MODE=auto), and runs python -m video_url_analyzer_mcp. Use it as a command value in any MCP client that prefers a single executable.

Integration

Run scripts/configure_mcp_clients.ps1 for an interactive menu, or copy the snippets below from docs/mcp-config-examples.md. The wizard backs up existing client config, validates JSON/TOML, and never overwrites unrelated MCP servers.

Client configs use video-analyzer as the local MCP server entry name. The published package remains video-url-analyzer-mcp, and the registry name remains io.github.u2n4/video-url-analyzer-mcp.

Claude Desktop (`%APPDATA%\Claude\claude_desktop_config.json`)

json

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

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

The wizard prefers leaving the API key in your OS environment. If you must embed it, add "env": { "GEMINI_API_KEY": "YOUR_KEY_HERE" }.

Claude Code (CLI)

Or, after pip install -e . in the repo:

Codex CLI (`~/.codex/config.toml`)

VS Code / GitHub Copilot MCP

Workspace registration writes .vscode/mcp.json:

json

{  "inputs": [    {      "type": "promptString",      "id": "video-url-analyzer-gemini-api-key",      "description": "Gemini API key for video-url-analyzer-mcp",      "password": true    }  ],  "servers": {    "video-analyzer": {      "type": "stdio",      "command": "uvx",      "args": ["video-url-analyzer-mcp"],      "env": {        "GEMINI_API_KEY": "${input:video-url-analyzer-gemini-api-key}"      }    }  }}

{  "inputs": [    {      "type": "promptString",      "id": "video-url-analyzer-gemini-api-key",      "description": "Gemini API key for video-url-analyzer-mcp",      "password": true    }  ],  "servers": {    "video-analyzer": {      "type": "stdio",      "command": "uvx",      "args": ["video-url-analyzer-mcp"],      "env": {        "GEMINI_API_KEY": "${input:video-url-analyzer-gemini-api-key}"      }    }  }}

For all clients, restart the application after editing config so the new MCP server is picked up. Full snippets — including Cursor, Windsurf, Antigravity (%USERPROFILE%\.gemini\antigravity\mcp_config.json), and Cline — live in docs/mcp-config-examples.md.

Usage Examples

python

# Full video analysis with Gemini 3.5 Flashanalyze_video("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
# Custom analysis promptanalyze_video("https://www.tiktok.com/@user/video/123",              prompt="List every product shown and estimate prices")
# Multilingual transcript extractionget_transcript("https://www.instagram.com/reel/ABC123/", lang="ar")
# Ask specific questions about video contentask_about_video("https://youtu.be/abc",                question="What programming language is used in the tutorial?")
# Analyze once, then ask locally from the saved contextprepare_video_context("https://youtu.be/abc", detail="standard")ask_video_context("https://youtu.be/abc",                  question="What happens near the end?")
# Extract visual evidence without embedding binary data in the tool outputget_video_frame("https://youtu.be/abc", timestamp="00:30")get_video_clip("https://youtu.be/abc", start="00:20", end="00:28")
# Watch & build — extract tutorial stepswatch_and_analyze("https://www.youtube.com/watch?v=tutorial123")

# Full video analysis with Gemini 3.5 Flashanalyze_video("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
# Custom analysis promptanalyze_video("https://www.tiktok.com/@user/video/123",              prompt="List every product shown and estimate prices")
# Multilingual transcript extractionget_transcript("https://www.instagram.com/reel/ABC123/", lang="ar")
# Ask specific questions about video contentask_about_video("https://youtu.be/abc",                question="What programming language is used in the tutorial?")
# Analyze once, then ask locally from the saved contextprepare_video_context("https://youtu.be/abc", detail="standard")ask_video_context("https://youtu.be/abc",                  question="What happens near the end?")
# Extract visual evidence without embedding binary data in the tool outputget_video_frame("https://youtu.be/abc", timestamp="00:30")get_video_clip("https://youtu.be/abc", start="00:20", end="00:28")
# Watch & build — extract tutorial stepswatch_and_analyze("https://www.youtube.com/watch?v=tutorial123")

Security

This server has been hardened against a comprehensive threat model audit:

Layer	Protection
SSRF	URL allowlist — only YouTube, TikTok, Instagram domains accepted. Private IPs, localhost, `file://` blocked.
Command Injection	`shell=False` + `shlex.split()`. Dangerous command blocklist (rm -rf, reverse shells, eval, pipe-to-shell).
Path Traversal	25+ sensitive path patterns blocked (`.ssh`, `.aws`, `.env`, system dirs, AppData).
TLS	Full certificate validation on all downloads.
Browser Cookies	Opt-in only via `VIDEO_ANALYZER_COOKIES=true`. Disabled by default.
Download Size	Hard limit of 100 MB per video.
DoS Protection	Max 10 concurrent background jobs. Auto-expiry after 1 hour. Storage cap of 200 analyses.
Schema Validation	Gemini JSON responses validated before execution. Response size capped at 500K chars.
Dependencies	Runtime dependency bounds are maintained in `pyproject.toml`.

Environment Variables

Variable	Description	Default
`GEMINI_API_KEY`	Google Gemini API key	Required
`ANALYSES_DIR`	Directory for saved analyses	`./analyses`
`VIDEO_CONTEXT_DIR`	Directory for saved reusable video contexts	`video_contexts`
`VIDEO_SOURCE_DIR`	Directory for cached downloaded source media	`video_sources`
`VIDEO_ASSET_DIR`	Directory for extracted frames/clips	`video_assets`
`VIDEO_ANALYZER_COOKIES`	Enable browser cookie access (`true`/`false`)	`false`
`VIDEO_DOWNLOAD_TIMEOUT`	Override download and yt-dlp timeout values, in seconds	Existing per-operation defaults
`VIDEO_FFMPEG_TIMEOUT`	Override ffmpeg extraction timeout values, in seconds	Existing per-operation defaults
`VIDEO_GEMINI_TIMEOUT`	Optional Gemini HTTP timeout, in seconds	SDK default
`VIDEO_IMAGE_DOWNLOAD_CONCURRENCY`	Parallel image downloads for TikTok/Instagram/YouTube photo posts	`6`
`VIDEO_GEMINI_UPLOAD_CONCURRENCY`	Parallel Gemini Files uploads for downloaded media and slideshow images	`4`
`VIDEO_ANALYZER_MODEL`	Single-knob default model id used for both fast and deep model resolution. Per-call `model=` and `GEMINI_FAST_MODEL` / `GEMINI_DEEP_MODEL` still take precedence.	unset
`GEMINI_FAST_MODEL`	Override for compact/standard detail mode	`gemini-3.5-flash`
`GEMINI_DEEP_MODEL`	Override for `full` detail mode	`gemini-3.1-pro-preview`

Default fast model: gemini-3.5-flash. Default deep model (used when detail="full"): gemini-3.1-pro-preview. Set VIDEO_ANALYZER_MODEL to override both at once. Model availability can vary by Google account, region, and API tier — fall back to gemini-flash-latest if the latest ids are not yet enabled for your key. | VIDEO_ANALYZER_MODE | Behavior preset (auto / api / client / local); read by start.bat | auto |

Troubleshooting

Issue	Solution
`GEMINI_API_KEY not set`	Create `.env` file or pass via environment variable
TikTok download fails	tikwm.com fallback activates automatically. Ensure `curl_cffi` is installed.
TikTok `bvc2` / `bytevc2` codec	v1.4 avoids these unsupported ByteDance streams when a compatible MP4 H.264/H.265 format exists. If no compatible stream is available, tools return a structured `unsupported_codec` or `no_compatible_format` error instead of uploading or pretending success.
Instagram download fails	`pip install curl_cffi` for browser impersonation support
`ENOENT` on Windows	Use `start.bat` as command in Claude Desktop config
Impersonate target not available	Reinstall: `pip install "yt-dlp[curl-cffi]"`
Claude Desktop timeout	TikTok/Instagram run in background — use `check_analysis_job(job_id)` to poll
Background job says failed	Expected when the worker result is an error, Gemini file processing fails, or media validation rejects the source. `check_analysis_job` no longer reports these inner failures as completed.
`prepare_video_context` repeats work	It reuses cached contexts unless `force_refresh=true`
YouTube `source.mp4` missing	Expected in some cases. Frame/clip tools can recover from the saved URL and use `yt-dlp -g` + ffmpeg fast extraction.
Transient Gemini 503/5xx	Gemini `generate_content` calls retry up to 3 times with exponential backoff. 4xx auth/schema/user errors are not retried.

Tech Stack

Technology	Version	Purpose
Google Gemini 3.5 Flash	Latest	Multimodal video analysis engine
FastMCP	3.3.1+	MCP protocol framework
yt-dlp	2026.3.17+	Video downloader
curl_cffi	>=0.7.4,<0.15.0	Browser impersonation (TLS fingerprint), pinned for yt-dlp 2026.03.17 compatibility
google-genai	2.5.0+	Official Google GenAI SDK

License

MIT

العربية

[خادم تحليل الفيديو]

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

خادم MCP لتحليل الفيديو باستخدام Google Gemini 3.5 Flash — احدث نموذج Gemini Flash متعدد الوسائط من جوجل.

المميزات

الاداة	الوصف
`analyze_video`	تحليل شامل للصوت والصورة مع دعم الاوامر المخصصة
`get_transcript`	استخراج النص المنطوق مع الطوابع الزمنية — يدعم +100 لغة
`ask_about_video`	اسال اي سؤال عن محتوى الفيديو
`prepare_video_context`	تحليل الفيديو مرة واحدة وحفظ سياق محلي قابل لاعادة الاستخدام
`ask_video_context`	الاجابة من السياق المحفوظ بدون Gemini افتراضيا
`get_video_frame` / `get_video_clip`	استخراج صورة او مقطع كدليل محلي، مع مسار سريع ليوتيوب عبر yt-dlp + ffmpeg
`watch_and_analyze`	استخراج خطوات الشروحات التقنية والاوامر والاكواد
`execute_tutorial_steps`	مراجعة وتنفيذ الخطوات المستخرجة بامان

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

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

التثبيت السريع (ويندوز)

استنسخ الريبو ثم شغل المعالج التفاعلي: