Video URL Analyzer MCP

What is This?

Video URL Analyzer MCP is a Model Context Protocol (MCP) server that lets Claude (or any MCP-compatible AI) analyze videos from YouTube, TikTok, and Instagram — just paste a URL. Powered by Google's Gemini API with full audio + visual analysis, it extracts transcripts, provides AI-powered insights, and can even extract executable tutorial steps.

30-second demo

Paste a YouTube, TikTok, or Instagram URL into Claude and ask:

Analyze this video. Give me:
1. a concise summary
2. transcript highlights with timestamps
3. important visual details not obvious from the transcript
4. any tools, commands, products, or code shown on screen

Video URL Analyzer MCP turns a video link into structured context: transcript, visual understanding, Q&A, and tutorial extraction.

Features

• YouTube Analysis — Direct analysis via Gemini API (no download needed)
• TikTok & Instagram — Async job pattern with yt-dlp download + Gemini Files API
• Full Audio + Visual — Analyzes both video frames AND audio/speech
• 6 Tools — analyze, transcript, Q&A, watch & analyze, execute tutorials, check jobs
• Bilingual — Supports Arabic and English prompts and responses
• Async Jobs — Background processing prevents Claude Desktop timeout crashes
• Security Hardened — URL allowlist, SSRF protection, command injection prevention, path traversal blocking
• Zero-Config Install — uvx video-url-analyzer-mcp and you are running

Supported Platforms

YouTube videos are analyzed directly through Gemini's native video understanding — zero download, zero upload, maximum speed.

Quick Start

Option 1: uvx (Recommended)

Requires uv.

Claude Desktop -- add to 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 -- add to .cursor/mcp.json or .vscode/mcp.json:

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

Windsurf -- add to ~/.codeium/windsurf/mcp_config.json:

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

Claude Code on Windows

# Install uv if needed
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Restart PowerShell, then add the MCP server
claude mcp add video-analyzer -s user -e GEMINI_API_KEY=your_key -- uvx video-url-analyzer-mcp

# Verify
claude mcp list

Option 2: pip install

pip install video-url-analyzer-mcp

Option 3: From source

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

Tools

Safety note: execute_tutorial_steps is intended for reviewed, user-approved tutorial steps. Treat commands extracted from videos as untrusted. Prefer review/dry-run first, and do not execute commands from unknown videos without understanding them.

• Default behavior is review-oriented.
• confirm=true may execute commands.
• Users must review and understand commands before execution.

How It Works

YouTube — Synchronous: URL is sent directly to Gemini API for instant analysis (no download).

TikTok & Instagram — Asynchronous: Video is downloaded via yt-dlp, uploaded to Gemini Files API, analyzed, then cleaned up. Returns a job_id immediately — poll with check_analysis_job.

Privacy & Data Flow

This server is designed to be explicit about where video data goes.

Notes:

• GEMINI_API_KEY is required for full multimodal analysis in the current version.
• Browser cookies are disabled by default and only used if VIDEO_ANALYZER_COOKIES=true.
• Analysis results may be stored in ANALYSES_DIR depending on configuration.
• Do not analyze private, sensitive, or confidential videos unless you are comfortable with this data flow.

Usage Examples

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

Try it

Analyze this YouTube video and give me a summary, transcript highlights, and visual details.

Ask this video: what tools, apps, products, or commands appear on screen?

Watch this tutorial and extract the steps, commands, file paths, and warnings. Do not execute anything.

حلل هذا الفيديو بالعربي، وطلع لي الملخص، أهم النقاط، وأي أوامر أو أدوات تظهر في الشرح.

Architecture

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

Platform Detection

URLs are automatically routed to the correct pipeline:

• 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/

Security

This server has been hardened against a comprehensive threat model:

Known Limitations

• Requires GEMINI_API_KEY for full video understanding in the current version.
• TikTok and Instagram support can be affected by platform anti-bot changes.
• Private, deleted, region-locked, or login-required videos may fail.
• Very long videos may hit provider limits, take longer, or cost more.
• TikTok/Instagram processing is asynchronous; use check_analysis_job to poll status.
• Results depend on Gemini model availability, API quota, and rate limits.
• Transcript quality depends on audio clarity, language, captions, and platform metadata.

Configuration

Tech Stack

Troubleshooting

No API Key / Client AI Fallback Roadmap

Gemini API provides the best current experience because it can analyze audio and visuals together.

A future fallback mode is planned for users who do not want to provide an API key or when the API is unavailable:

Video URL
→ extract metadata, captions/transcript, and selected keyframes locally
→ return structured context to the MCP client
→ let the user's AI client analyze the prepared context

Planned modes:

Important: Client AI fallback quality will depend on the MCP client. Some MCP clients may not pass image content from tool results to the model reliably, so transcript/metadata fallback will remain important.

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT — see LICENSE.

Support

If you find this useful, please star this repository!

Made with ❤️ in the Eastern Province of Saudi Arabia.

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