This MCP server analyzes videos from YouTube, TikTok, and Instagram using Google Gemini AI, offering transcription, Q&A, tutorial extraction, context management, and more.
Analyze videos (analyze_video): Comprehensive audio + visual analysis with optional custom prompts.
Extract transcripts (get_transcript): Timestamped transcripts with speaker identification in 100+ languages.
Ask questions (ask_about_video): Query specific video content using natural language.
Find moments (find_video_moments): Locate matching moments with structured output.
Analyze segments (analyze_video_segment): Focus analysis on a specific time range.
Manage contexts (prepare_video_context / ask_video_context): Save reusable video contexts for local follow-up queries, reducing re-analysis costs; list/delete as needed.
Extract assets (get_video_frame / get_video_clip): Capture frames or short clips (30s cap); retrieve evidence assets.
Tutorial analysis (watch_and_analyze): Extract shell commands, code snippets, file paths, and step-by-step instructions from technical videos.
Execute tutorial steps (execute_tutorial_steps): Safely review and optionally execute extracted steps — defaults to dry-run; requires explicit confirm=true.
Background jobs (check_analysis_job): Poll async job status for TikTok/Instagram downloads via a returned job ID.
Cache management (list_video_sources / cleanup_video_cache): Inspect metadata and clean up cached files.
Platform behavior: YouTube videos are analyzed instantly via Gemini's native understanding (no download needed); TikTok and Instagram videos are processed asynchronously in the background. Security hardening includes SSRF, command injection, and path traversal protections. Behavior is configurable via environment variables (API keys, models, timeouts, storage paths).
Analyze Instagram videos/reels from URL with async processing, extracting transcripts, AI insights, and Q&A capabilities.
Analyze TikTok videos from URL with async processing, extracting transcripts, AI insights, and Q&A capabilities.
Analyze YouTube videos from URL, extract transcripts, AI insights, tutorial steps, and perform Q&A on video content.
v1.6.0 exposes 18 MCP tools:
Tool | What it does |
| Full audio + visual analysis with custom prompts. Uses Gemini multimodal understanding. |
| Extract timestamped transcript with speaker identification. Supports 100+ languages via auto-detection. |
| Ask any question about the video content. |
| Return ordered slideshow images as MCP image blocks so Claude/the client AI can inspect them directly. |
| Find matching moments with compact/standard/full structured output. |
| Analyze only a selected time range. |
| Analyze once and save a reusable local context for follow-up questions and evidence lookup. |
| Answer from saved context by default; Gemini reanalysis is explicit opt-in. |
| List saved local contexts. |
| Delete one saved context. |
| Extract a local still frame, using the YouTube fast path when possible. |
| Extract a short local clip, with a 30s cap and YouTube fast path when possible. |
| Select saved evidence and return a frame or clip reference. |
| Inspect local source/context/asset cache metadata. |
| Dry-run or clean managed cache files; dry-run is the default. |
| Extract tutorial steps, shell commands, code snippets, and file paths from technical videos. |
| Validate and review extracted steps safely; executes only with confirmation. |
| Poll background job status for TikTok/Instagram async downloads. |
Platform | Method | Speed |
YouTube | Direct Gemini analysis — no download needed for analysis. Frame/clip extraction uses | 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 | ~8s |
Page scrape via curl_cffi (fast) → yt-dlp fallback | ~10s |
Platform | Post type | Handling |
TikTok | Photo Mode slideshow | Downloads all images, extracts the music/audio track when available, and sends one multimodal Gemini request. |
Carousel / single-photo posts | Downloads image slides in order and analyzes them as one post; mixed video slides are skipped with metadata. | |
YouTube | Community | Scrapes |
YouTube videos are analyzed directly through Gemini's native video understanding — zero download, zero upload, maximum speed. For YouTube evidence assets,
source.mp4is not always required: saved contexts keep the original URL, so frame/clip tools can use the local stream fast path later.
Related MCP server: Social → Context
Component | Role |
Gemini 3.8 Flash | Latest Flash model, the fast default: full audio + visual understanding in a single pass |
Gemini 4 Argon | Latest flagship reasoning model, the deep default for |
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 |
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. |
These are behavior modes, not tool names:
Mode | Behavior |
| Default adaptive behavior: YouTube direct analysis; TikTok/Instagram fast API/scrape then yt-dlp fallback; saved contexts reused when available. |
| Gemini-backed analysis or reanalysis. This is used by analysis tools and explicit Gemini opt-ins. |
| MCP client workflow mode: long TikTok/Instagram analysis returns a background |
| Saved-context, cache, frame, and clip operations that avoid Gemini unless explicitly requested. |
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.
irm https://raw.githubusercontent.com/u2n4/video-url-analyzer-mcp/main/install.ps1 | iexThe 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.
uvx (no install)uvx video-url-analyzer-mcpWorks on Windows / macOS / Linux as long as uv is on PATH.
git clone https://github.com/u2n4/video-url-analyzer-mcp.git
cd video-url-analyzer-mcp
powershell -ExecutionPolicy Bypass -File scripts\install_windows.ps1The 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 never printed; the wizard shows
only their length.
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.
git clone https://github.com/u2n4/video-url-analyzer-mcp.git
cd video-url-analyzer-mcp
pip install -e .
python -m video_url_analyzer_mcpGet 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 put it in a gitignored .env file in the repo root. The
server reads .env. start.bat also reads .env.keys.local, which the
wizard writes.
start.bat loads .env.keys.local (if present), sets VIDEO_ANALYZER_MODE=auto
when it is unset, and runs python -m video_url_analyzer_mcp. It sets no model id,
so the model variables from your environment or .env apply, as the table below
describes.
Use it as a command value in any MCP client that prefers a single
executable.
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.
%APPDATA%\Claude\claude_desktop_config.json){
"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 mcp add video-analyzer --transport stdio -- uvx video-url-analyzer-mcpOr, after pip install -e . in the repo:
claude mcp add video-analyzer --transport stdio -- python -m video_url_analyzer_mcp~/.codex/config.toml)[mcp_servers.video-analyzer]
command = "uvx"
args = ["video-url-analyzer-mcp"]Workspace registration writes .vscode/mcp.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}"
}
}
}
}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.
# Full video analysis with Gemini 3.8 Flash
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?")
# Analyze once, then ask locally from the saved context
prepare_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 output
get_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 steps
watch_and_analyze("https://www.youtube.com/watch?v=tutorial123")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, |
Command Injection |
|
Path Traversal | 25+ sensitive path patterns blocked ( |
TLS | Full certificate validation on all downloads. |
Browser Cookies | Opt-in only via |
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 |
Variable | Description | Default |
| Google Gemini API key | Required |
| Root for the four data directories below | OS user-data directory, e.g. |
| Directory for saved analyses |
|
| Directory for saved reusable video contexts |
|
| Directory for cached downloaded source media |
|
| Directory for extracted frames/clips |
|
| Enable browser cookie access ( |
|
| Extra whole program names that tutorial steps may run, comma-separated (for example | unset (built-in list only) |
| Override download and yt-dlp timeout values, in seconds | Existing per-operation defaults |
| Override ffmpeg extraction timeout values, in seconds | Existing per-operation defaults |
| Optional Gemini HTTP timeout, in seconds | SDK default |
| Parallel image downloads for TikTok/Instagram/YouTube photo posts |
|
| Parallel Gemini Files uploads for downloaded media and slideshow images |
|
| Single-knob default model id used for both fast and deep model resolution. Per-call | unset |
| Override for compact/standard detail mode |
|
| Override for |
|
| Informational only: |
|
Default fast model:
gemini-3.8-flash. Default deep model (used whendetail="full"):gemini-4-argon. SetVIDEO_ANALYZER_MODELto override both at once. Model availability can vary by Google account, region, and API tier. Ids were checked against https://aistudio.google.com/docs/models on 2026-11-05.
Issue | Solution |
| Create |
TikTok download fails | tikwm.com fallback activates automatically. Ensure |
TikTok | 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 |
Instagram download fails |
|
| Use |
Impersonate target not available | Reinstall: |
Claude Desktop timeout | TikTok/Instagram run in background — use |
Background job says failed | Expected when the worker result is an error, Gemini file processing fails, or media validation rejects the source. |
| It reuses cached contexts unless |
YouTube | Expected in some cases. Frame/clip tools can recover from the saved URL and use |
Transient Gemini 503/5xx | Gemini |
Technology | Version | Purpose |
Latest Flash (fast default) | Multimodal video analysis engine | |
Latest flagship (deep default) | Reasoning over long video, | |
3.3.1+ | MCP protocol framework | |
2026.3.17+ | Video downloader | |
>=0.7.4,<0.15.0 | Browser impersonation (TLS fingerprint), pinned for yt-dlp 2026.03.17 compatibility | |
2.5.0+ | Official Google GenAI SDK |
MIT
خادم MCP لتحليل الفيديو باستخدام Google Gemini 3.8 Flash — احدث نموذج Gemini Flash متعدد الوسائط من جوجل.
الاداة | الوصف |
| تحليل شامل للصوت والصورة مع دعم الاوامر المخصصة |
| استخراج النص المنطوق مع الطوابع الزمنية — يدعم +100 لغة |
| اسال اي سؤال عن محتوى الفيديو |
| تحليل الفيديو مرة واحدة وحفظ سياق محلي قابل لاعادة الاستخدام |
| الاجابة من السياق المحفوظ بدون Gemini افتراضيا |
| استخراج صورة او مقطع كدليل محلي، مع مسار سريع ليوتيوب عبر yt-dlp + ffmpeg |
| استخراج خطوات الشروحات التقنية والاوامر والاكواد |
| مراجعة وتنفيذ الخطوات المستخرجة بامان |
المنصة | السرعة |
يوتيوب | فوري — تحليل مباشر بدون تحميل |
تيك توك | ~8 ثواني — واجهة tikwm.com السريعة |
انستقرام | ~10 ثواني — استخراج مباشر من الصفحة |
استنسخ الريبو ثم شغل المعالج التفاعلي:
git clone https://github.com/u2n4/video-url-analyzer-mcp.git
cd video-url-analyzer-mcp
powershell -ExecutionPolicy Bypass -File scripts\install_windows.ps1البديل بدون تثبيت: uvx video-url-analyzer-mcp.
الخادم محمي ضد:
SSRF — قائمة بيضاء للنطاقات المسموحة فقط
حقن الاوامر — قائمة السماح بالبرامج + تنفيذ بدون shell
اختراق المسارات — حظر 25+ مسار حساس
حماية من الحمل الزائد — حد اقصى 10 مهام متزامنة
اذهب الى Google AI Studio
انشئ مفتاح API مجاني
ضعه في ملف .env:
GEMINI_API_KEY=مفتاحك_هناAnalyze a video or photo/slideshow post from YouTube, TikTok, or Instagram.
Provides comprehensive audio + visual analysis using Gemini AI. Works with videos AND photo/slideshow posts on TikTok, Instagram, and YouTube community posts. YouTube videos are analyzed directly and return the result immediately. TikTok and Instagram videos are processed in the background — the tool returns a job_id. Use check_analysis_job(job_id) to poll for the result.
Inputs: url (required), model, prompt. Returns: result
Analyze only a selected video segment.
Uses Gemini video_metadata clipping when available. Gemini performs video/audio/visual reasoning. detail controls model + max_output_tokens + thinking/media config.
Inputs: end (required), url (required), start (required), model, +3 more. Returns: result
Ask a specific question about a video or photo/slideshow post.
Works with videos AND photo/slideshow posts on TikTok, Instagram, and YouTube community posts. YouTube returns the answer immediately. TikTok/Instagram return a job_id — use check_analysis_job(job_id) to poll for the result.
Inputs: url (required), question (required), model. Returns: result
Answer a question from saved video context without Gemini by default.
Inputs: question (required), video_id_or_url (required), detail, use_gemini, +1 more. Returns: result
Check the status of a background video analysis job.
When analyze_video, get_transcript, ask_about_video, or watch_and_analyze returns a job_id (for TikTok/Instagram videos), use this tool to poll for the result. Keep calling until status is "completed" or "failed".
Inputs: job_id (required). Returns: result
Inspect or clean managed video cache files. Safe dry-run by default.
Inputs: scope, dry_run, video_id. Returns: result
Delete one saved local video context file.
Inputs: video_id_or_url (required). Returns: result
Review or execute tutorial steps extracted by watch_and_analyze.
SAFETY: By default (confirm=false), this only shows a summary of what WOULD be executed. Set confirm=true ONLY after reviewing the steps.
Inputs: steps_json (required), confirm. Returns: result
Find moments in a video matching a semantic query.
Gemini performs the video/audio/visual reasoning. detail controls model + max_output_tokens + thinking/media config. compact is default and returns concise structured JSON.
Inputs: url (required), query (required), model, detail, +3 more. Returns: result
Extract speech transcript from a video or slideshow audio track.
YouTube returns the result immediately. TikTok/Instagram return a job_id — use check_analysis_job(job_id) to poll for the result. Slideshows without audio return a structured slideshow_no_audio response.
Inputs: url (required), lang, model. Returns: result
Extract a local video clip under 30 seconds and return metadata.
Inputs: end (required), start (required), video_id_or_url (required), reason, +3 more. Returns: result
Find saved visual evidence and return a local frame/clip reference.
Inputs: request (required), video_id_or_url (required), asset_type, preferred_end, +3 more. Returns: result
Extract a local still frame and return compact asset metadata.
Inputs: timestamp (required), video_id_or_url (required), reason, force_refresh, +1 more. Returns: result
List saved local video context files.
Inputs: limit, filter_text. Returns: result
List cached video sources, contexts, and assets. Never calls Gemini.
Inputs: limit, filter_text. Returns: result
Return slideshow images as ordered MCP image blocks for client-side vision.
This tool does not call Gemini. It downloads TikTok Photo Mode, Instagram photo/carousel posts, or YouTube community post images, then returns each image directly to the MCP client with an explicit image_index label. Use it when you want Claude/the client AI to inspect the images itself instead of receiving a Gemini-generated analysis.
Inputs: url (required), include_audio. Returns: result
Analyze a whole video once and save a local structured context.
Inputs: url (required), model, detail, chunk_seconds, +1 more. Returns: result
Watch a video tutorial and extract all technical steps, commands, and code.
Downloads the video, analyzes it with Gemini AI, and returns structured JSON with every command, code snippet, file path, and tool mentioned. YouTube returns the result immediately. TikTok/Instagram return a job_id — use check_analysis_job(job_id) to poll for the result.
This tool ONLY analyzes — it does NOT execute anything. Use execute_tutorial_steps to run the extracted steps after review.
Inputs: url (required), lang, model. Returns: result
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 18 tools
Several tools have overlapping purposes, such as analyze_video, watch_and_analyze, and prepare_video_context all performing analysis, and multiple get_* tools for extracting clips/frames. While descriptions provide some differentiation, an agent could easily confuse them.
Tool names consistently use verb_noun snake_case (e.g., analyze_video, get_transcript). Minor deviations include ask_video_context (missing preposition) and watch_and_analyze (compound verb), but overall pattern is predictable.
18 tools is somewhat high for a video analyzer, covering analysis, Q&A, extraction, and management. The count is at the upper bound of reasonable, but many tools are specialized and the scope justifies most.
The tool surface covers analysis, Q&A, transcript, moments, clips, context management, and tutorial extraction. Missing operations like updating sources or more advanced editing, but core workflows are well-supported.
Transcripts and AI summaries of TikTok, YouTube, Instagram, Facebook and X videos from a link.
Turn YouTube, TikTok, Instagram, Facebook, X and article URLs into transcripts, comments and JSON.
Any video URL to LLM-ready transcript. ASR built in, no captions needed. TikTok, X, TED and more.
Turn a TikTok/Instagram/YouTube link into text for your AI: metadata, transcript and image OCR.
