Video URL Analyzer MCP

MCP server to analyze YouTube, TikTok & Instagram videos from URL — transcripts, AI insights, tutorial extraction

Features · Quick Start · Tools · Usage · Security · العربية

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.

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" }
    }
  }
}

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

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.

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

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:

Configuration

Tech Stack

Troubleshooting

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 .