io.github.u2n4/video-url-analyzer-mcp

Features

v1.5.4 exposes 18 MCP tools:

Supported Platforms

Photo / Slideshow Posts

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

Operating Modes

These are behavior modes, not tool names:

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)

irm https://raw.githubusercontent.com/u2n4/video-url-analyzer-mcp/main/install.ps1 | iex

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)

uvx video-url-analyzer-mcp

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

Option C — Windows wizard from a checkout

git clone https://github.com/u2n4/video-url-analyzer-mcp.git
cd video-url-analyzer-mcp
powershell -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)

git clone https://github.com/u2n4/video-url-analyzer-mcp.git
cd video-url-analyzer-mcp
pip 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)

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

claude mcp add video-analyzer --transport stdio -- uvx video-url-analyzer-mcp

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

claude mcp add video-analyzer --transport stdio -- python -m video_url_analyzer_mcp

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

[mcp_servers.video-analyzer]
command = "uvx"
args = ["video-url-analyzer-mcp"]

VS Code / GitHub Copilot 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.

Usage Examples

# Full video analysis with Gemini 3.5 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")

Security

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

Environment Variables

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

Tech Stack

License

MIT

العربية

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

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

المميزات

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

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

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

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 مهام متزامنة

الحصول على مفتاح API

1. اذهب الى Google AI Studio
2. انشئ مفتاح API مجاني
3. ضعه في ملف .env:

GEMINI_API_KEY=مفتاحك_هنا