这是什么？

Video URL Analyzer MCP 是一个模型上下文协议 (MCP) 服务器，允许 Claude（或任何兼容 MCP 的 AI）分析来自 YouTube、TikTok 和 Instagram 的视频 — 只需粘贴 URL 即可。它由 Google Gemini API 提供支持，具备完整的音频和视觉分析能力，可以提取字幕、提供 AI 驱动的见解，甚至可以提取可执行的教程步骤。

功能

YouTube 分析 — 通过 Gemini API 直接分析（无需下载）
TikTok 和 Instagram — 采用异步作业模式，结合 yt-dlp 下载和 Gemini Files API
完整的音频 + 视觉 — 同时分析视频帧和音频/语音
6 种工具 — 分析、字幕、问答、观看并分析、执行教程、检查作业
双语支持 — 支持阿拉伯语和英语的提示词与响应
异步作业 — 后台处理可防止 Claude Desktop 超时崩溃
安全加固 — URL 白名单、SSRF 防护、命令注入防护、路径遍历拦截
零配置安装 — 使用 uvx video-url-analyzer-mcp 即可运行

支持的平台

平台	方法	速度
YouTube	直接 Gemini 分析 — 无需下载	瞬时
TikTok	tikwm.com API (快速) → `yt-dlp` 后备	~8秒
Instagram	通过 `curl_cffi` 页面抓取 (快速) → `yt-dlp` 后备	~10秒

YouTube 视频通过 Gemini 原生的视频理解能力直接分析 — 零下载、零上传，速度最快。

快速开始

选项 1：uvx (推荐)

需要 uv。

Claude Desktop -- 添加到 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 -- 添加到 .cursor/mcp.json 或 .vscode/mcp.json：

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

Windsurf -- 添加到 ~/.codeium/windsurf/mcp_config.json：

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

选项 2：pip 安装

pip install video-url-analyzer-mcp

选项 3：从源码安装

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

工具

工具	功能
`analyze_video`	使用自定义提示词进行完整的音频 + 视觉分析。利用 Gemini 实现最先进的多模态理解。
`get_transcript`	提取带时间戳的字幕并识别说话人。通过自动检测支持 100 多种语言。
`ask_about_video`	提出任何问题 — “出现了多少人？”，“0:45 处显示的是什么品牌？”，“总结主要论点。”
`watch_and_analyze`	从技术视频中提取教程步骤、Shell 命令、代码片段和文件路径。
`execute_tutorial_steps`	安全地审查提取的步骤，并在确认后执行。通过命令和路径验证进行沙盒隔离。
`check_analysis_job`	轮询 TikTok/Instagram 异步下载的后台作业状态。

工作原理

YouTube — 同步：URL 直接发送到 Gemini API 进行即时分析（无需下载）。

TikTok 和 Instagram — 异步：视频通过 yt-dlp 下载，上传到 Gemini Files API 进行分析，然后清理。立即返回 job_id — 使用 check_analysis_job 进行轮询。

使用示例

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

架构

组件	角色
Gemini API	多模态模型 — 一次性完成完整的音频 + 视觉理解
FastMCP 3.x	基于 stdio 传输的 MCP 协议框架
yt-dlp + curl_cffi	视频下载，通过 Chrome 浏览器模拟绕过反爬虫机制
tikwm.com API	当 `yt-dlp` 被 WAF 拦截时的 TikTok 快速路径后备
后台作业	TikTok/Instagram 的异步线程，防止 Claude Desktop 超时

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

平台检测

URL 会自动路由到正确的处理管道：

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/

安全性

本服务器已针对全面的威胁模型进行了加固：

层级	防护
SSRF	URL 白名单 — 仅接受 YouTube、TikTok、Instagram 域名。私有 IP、localhost、`file://` 被拦截。
命令注入	`shell=False` + `shlex.split()`。危险命令黑名单（rm -rf, 反向 Shell, eval, 管道到 Shell）。
路径遍历	拦截 25+ 个敏感路径模式（`.ssh`, `.aws`, `.env`, 系统目录, AppData）。
TLS	所有下载均进行完整的证书验证。
浏览器 Cookie	仅通过 `VIDEO_ANALYZER_COOKIES=true` 启用。默认禁用。
下载大小	每个视频硬性限制为 100 MB。
DoS 防护	最多 10 个并发后台作业。1 小时后自动过期。存储上限为 200 次分析。
模式验证	Gemini JSON 响应在执行前经过验证。响应大小限制为 50 万字符。
依赖项	所有版本均在 `pyproject.toml` 中锁定。

配置

变量	描述	默认值
`GEMINI_API_KEY`	Google Gemini API 密钥 (必需)	—
`ANALYSES_DIR`	存储分析结果的目录	`./analyses`
`VIDEO_ANALYZER_COOKIES`	为 `yt-dlp` 启用浏览器 Cookie	`false`

技术栈

技术	用途
google-genai	Google Gemini API SDK
FastMCP	MCP 协议框架
yt-dlp	视频下载器
curl_cffi	浏览器模拟 (TLS 指纹)
python-dotenv	环境变量加载

故障排除

问题	解决方案
`GEMINI_API_KEY not set`	创建 `.env` 文件或通过环境变量传递
TikTok 下载失败	tikwm.com 后备会自动激活。确保已安装 `curl_cffi`。
Instagram 下载失败	`pip install curl_cffi` 以支持浏览器模拟
Windows 上出现 `ENOENT`	使用 `uvx video-url-analyzer-mcp` 作为命令
Claude Desktop 超时	TikTok/Instagram 在后台运行 — 使用 `check_analysis_job(job_id)` 进行轮询
未找到 Python	从 python.org 安装 Python 3.10+

贡献

请参阅 CONTRIBUTING.md 获取指南。

许可证

MIT — 请参阅 LICENSE。

支持

如果您觉得有用，请给此仓库加星！

在沙特阿拉伯东部省份用心制作。

العربية

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

خادم MCP لتحليل الفيديو باستخدام Google Gemini — احدث واقوى نموذج ذكاء اصطناعي متعدد الوسائط من جوجل.

المميزات

الاداة	الوصف
`analyze_video`	تحليل شامل للصوت والصورة مع دعم الاوامر المخصصة
`get_transcript`	استخراج النص المنطوق مع الطوابع الزمنية — يدعم +100 لغة
`ask_about_video`	اسال اي سؤال عن محتوى الفيديو
`watch_and_analyze`	استخراج خطوات الشروحات التقنية والاوامر والاكواد
`execute_tutorial_steps`	مراجعة وتنفيذ الخطوات المستخرجة بامان

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

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

التثبيت السريع

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

الامان

الخادم محمي ضد:

SSRF — قائمة بيضاء للنطاقات المسموحة فقط
حقن الاوامر — حظر الاوامر الخطيرة + تنفيذ بدون shell
اختراق المسارات — حظر 25+ مسار حساس
حماية من الحمل الزائد — حد اقصى 10 مهام متزامنة

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

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

video-url-analyzer-mcp