Gemini Video MCP Server

Gemini 3 Pro MCP服务器-视频分析

一个模型上下文协议（MCP）服务器，可以使用谷歌的Gemini 2.5 Pro模型进行视频分析。使用强大的多模式AI功能分析文件、YouTube URL或内联数据中的视频。

特性

• 多种输入法:

- 上传本地视频文件（推荐用于长视频） - 直接分析YouTube视频 - 发送内联base64编码的视频数据（适用于小于20MB的小文件）

• 高级视频处理:

- 自定义帧率采样 - 带有开始/结束时间戳的视频剪辑 - 可配置的媒体分辨率（默认或低） - 带有视觉描述的音频转录 - 多视频比较

• 研究驱动的视频创作 ⭐ 新

- 谷歌搜索为现实世界的电影制作知识奠定了基础 - 自主研究区域检测（导演、摄影、色彩分级等） - 每个区域进行3-5次搜索的深入研究 - 具有可验证来源的引用丰富的输出 - 智能缓存（1周TTL）可减少API调用 - 综合管道：研究→ 自动生成提示

• 支持的视频格式:

- MP4、MPEG、MOV、AVI、FLV、MPG、WebM、WMV、3GPP

• 强大的能力:

- 视频摘要 - 基于时间戳的查询（“2:30时会发生什么？”） - 物体和场景检测 - 音频转录 - 视觉描述 - 视频对比分析 - 研究知情视频提示生成

安装

先决条件

• Python 3.10或更高版本
• 谷歌人工智能API密钥（在https://aistudio.google.com/apikey)

设置

1. 安装依赖项:

   pip install -r requirements.txt

1. 设置您的Google API密钥:

   export GOOGLE_API_KEY="your-api-key-here"

或者将其添加到您的shell配置文件中（~/.bashrc，~/.zshrc）：

   echo 'export GOOGLE_API_KEY="your-api-key-here"' >> ~/.bashrc
   source ~/.bashrc

运行服务器

使用MCP CLI（推荐）

# Run the server
mcp run gemini_video_mcp.py

# Or use the Python module directly
python gemini_video_mcp.py

在Claude Desktop中安装

将此添加到您的Claude Desktop配置中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json\ 视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "gemini-video": {
      "command": "python",
      "args": ["/absolute/path/to/gemini_video_mcp.py"],
      "env": {
        "GOOGLE_API_KEY": "your-api-key-here"
      }
    }
  }
}

或使用 uv 为了更好地管理依赖关系：

{
  "mcpServers": {
    "gemini-video": {
      "command": "uv",
      "args": ["run", "gemini_video_mcp.py"],
      "env": {
        "GOOGLE_API_KEY": "your-api-key-here"
      }
    }
  }
}

可用工具

1.分析_视频_文件

使用Gemini 2.5 Pro分析本地视频文件。

最佳：长度超过1分钟的视频、较大的文件，或者当您想在多个查询中重用文件时。

参数:

• video_path （必填）：视频文件的路径
• prompt （必填）：您的问题或指示
• model：要使用的模型（默认值：“gemini-3-flash-review”）
• start_offset：可选开始时间（例如“30s”、“1m30s”）
• end_offset：可选结束时间（例如，“120秒”、“2米”）
• fps：帧率采样，单位为每秒帧数（默认值：10）
• media_resolution：代币储蓄为“默认”或“低”

示例:

# Summarize a video
analyze_video_file(
    video_path="/path/to/video.mp4",
    prompt="Summarize this video in 3 bullet points"
)

# Analyze a specific time range
analyze_video_file(
    video_path="/path/to/lecture.mp4",
    prompt="What is the professor explaining?",
    start_offset="5m30s",
    end_offset="10m"
)

# Process a long video efficiently
analyze_video_file(
    video_path="/path/to/movie.mp4",
    prompt="Describe the plot",
    media_resolution="low"
)

2.分析\_ youtube \_视频

直接分析公共YouTube视频。

最佳：无需下载即可快速分析YouTube内容。

参数:

• youtube_url （必填）：YouTube视频URL（必须是公开的）
• prompt （必填）：您的问题或指示
• model：要使用的模型（默认值：“gemini-3-flash-review”）
• start_offset：可选开始时间
• end_offset：可选结束时间
• fps：帧率采样，单位为每秒帧数（默认值：10）

速率限制:

• 免费套餐：每天8小时的YouTube视频
• 付费等级：无限制

示例:

# Summarize a YouTube video
analyze_youtube_video(
    youtube_url="https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    prompt="Summarize the key points of this video"
)

# Analyze a specific moment
analyze_youtube_video(
    youtube_url="https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    prompt="What happens at timestamp 1:30?"
)

# Clip analysis
analyze_youtube_video(
    youtube_url="https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    prompt="Describe this section",
    start_offset="1m",
    end_offset="2m30s"
)

3.分析在线视频

分析作为base64编码数据提供的小视频。

最佳：当数据已经编码时，视频小于20MB。

参数:

• video_base64 （必填）：Base64编码视频数据
• prompt （必填）：您的问题或指示
• mime_type：视频MIME类型（默认值：“Video/mp4”）
• model：要使用的模型（默认值：“gemini-3-flash-review”）
• fps：帧率采样，单位为每秒帧数（默认值：10）

示例:

import base64

# Read and encode video
with open("small_video.mp4", "rb") as f:
    video_data = base64.b64encode(f.read()).decode()

# Analyze it
analyze_inline_video(
    video_base64=video_data,
    prompt="What objects appear in this video?"
)

4.转录_视频

通过可选的视觉描述从视频中转录音频。

最佳：创建讲座、会议或任何有口语内容的视频的成绩单。

参数:

• video_path （必填）：视频文件的路径
• include_visual_descriptions：包括视觉信息（默认值：True）
• model：要使用的模型（默认值：“gemini-3-flash-review”）
• fps：帧率采样，单位为每秒帧数（默认值：10）

示例:

# Full transcription with visual context
transcribe_video(
    video_path="/path/to/lecture.mp4",
    include_visual_descriptions=True
)

# Audio-only transcription
transcribe_video(
    video_path="/path/to/podcast.mp4",
    include_visual_descriptions=False
)

5.比较视频

比较两个视频以确定差异或相似之处。

最佳：版本比较、质量分析、变更检测。

参数:

• video_path1 （必填）：第一条视频路径
• video_path2 （必填）：第二条视频路径
• comparison_prompt （必填）：比较什么
• model：要使用的模型（默认值：“gemini-3-flash-review”）
• fps：两个视频的帧率采样（默认值：10）

示例:

# Compare two versions
compare_videos(
    video_path1="/path/to/version1.mp4",
    video_path2="/path/to/version2.mp4",
    comparison_prompt="What changed between these versions?"
)

# Quality comparison
compare_videos(
    video_path1="/path/to/original.mp4",
    video_path2="/path/to/compressed.mp4",
    comparison_prompt="Compare the visual quality"
)

6.研究_理念

使用谷歌搜索基础研究电影制作技术、导演风格和提示工程最佳实践，以增强视频创作。

最佳：在创建视频提示之前，获得全面的、有研究支持的见解。该工具根据您的概念自主确定要研究的领域。

参数:

• concept_description （必填）：研究视频概念的描述
• auto_generate：如果为True，则在研究后自动创建视频提示（默认值：False）
• output_path：研究标记文件的可选路径
• model：要使用的模型（默认值：“gemini-3-flash-review”）
• max_output_tokens：响应中的最大令牌数（默认值：65536）
• cache_ttl_hours：缓存生存时间（以小时为单位）（默认值：168=1周）

研究领域 （自动确定）：

• 董事：著名导演的电影制作风格、标志性技巧
• 电影摄影：相机角度、运动、镜头选择、取景技术
• 色彩分级：调色板、照明设置、情绪创造
• 讲故事：叙事结构、节奏、故事框架
• 文本到图像提示：人工智能图像生成提示的最佳实践
• 文本转视频提示：运动描述符、相机运动提示
• 构图：视觉构图规则，人工智能模型如何解释框架和距离

特性:

• 谷歌搜索暂停：具有可验证引用的实时网络研究
• 自主研究：AI根据您的概念确定要研究的领域
• 深入探究：每个研究领域3-5次搜索以获得全面覆盖
• 引文丰富的输出：所有发现都链接到源URL
• 智能缓存：缓存1周的结果以减少API调用
• 综合管道：可选择从研究中自动生成视频提示

示例:

# Standalone research (review before generating prompts)
research_video_concepts(
    concept_description="Film noir detective story with dramatic lighting"
)
# Returns: research_film_noir_detective_story.md with comprehensive findings

# Integrated pipeline (research + automatic prompt generation)
research_video_concepts(
    concept_description="Wes Anderson-style symmetrical comedy",
    auto_generate=True
)
# Returns: Research markdown + video_prompts_wes_anderson_style.md

# Research specific concept
research_video_concepts(
    concept_description="Cyberpunk music video with neon aesthetics and fast cuts",
    output_path="cyberpunk_research.md"
)

# Research with custom cache duration
research_video_concepts(
    concept_description="Documentary style interview with natural lighting",
    cache_ttl_hours=24  # Cache for 1 day only
)

示例输出结构:

# Video Concept Research: Film Noir Detective Story

## Directors
Research on film noir directors like Billy Wilder, Orson Welles, and their
signature techniques including Dutch angles, chiaroscuro lighting... [1](source)

### Sources
1. [Classic Film Noir Techniques](https://example.com/noir-techniques)

## Cinematography
Camera techniques specific to noir: low-angle shots creating menace,
high-contrast black and white photography... [2](source), [3](source)

### Sources
2. [Noir Cinematography Guide](https://example.com/cinematography)
3. [Film School: Camera Angles](https://example.com/angles)

[... additional research areas ...]

7.generate_video_pmpts（通过自动搜索增强）

根据文本描述生成逐场景视频创建提示，现在使用 默认情况下启用自动研究.

参数:

• video_idea （必填）：视频概念的文字描述
• output_path：输出markdown文件的可选路径
• pacing_style：可选显式起搏控制（“超速”、“快速”、“中等”、“慢速”）
• auto_research: 新 -生成前自动进行研究（默认值： 真)
• research_context: 新 -从research_video_cepts（）到研究降价的可选路径
• max_output_tokens：响应中的最大令牌数（默认值：65536）
• model：要使用的模型（默认值：“gemini-3-flash-review”）

增强功能:

• 自动研究（默认）：在生成提示之前，通过谷歌搜索自动研究电影制作技术
• 当 research_context 一旦提供，该工具就会将这些研究结果整合到即时生成中
• 确保提示符合专业电影制作标准和当前的人工智能视频生成最佳实践
• 自动应用研究技术（相机角度、颜色分级、构图规则）
• 集 auto_research=False 跳过研究并直接生成提示（更快，无需Google Search API调用）

示例:

# Default usage (WITH auto-research - recommended!)
generate_video_prompts(
    video_idea="30-second F1 car advertisement with dynamic POV and motion blur"
)
# This will:
# 1. Auto-research F1 cinematography, camera techniques, motion blur, etc.
# 2. Generate prompts informed by the research
# 3. Save both research_*.md and video_prompts_*.md files

# Fast mode (skip research)
generate_video_prompts(
    video_idea="A dramatic storm approaching a lighthouse at sunset",
    auto_research=False  # Skip research, generate directly
)

# Manual research workflow
# Step 1: Research separately
research_video_concepts(
    concept_description="Film noir detective story with dramatic lighting",
    output_path="noir_research.md"
)

# Step 2: Generate prompts with existing research
generate_video_prompts(
    video_idea="Film noir detective story with dramatic lighting",
    research_context="noir_research.md",
    auto_research=False  # Use provided research, don't research again
)

# Alternative: Use research_video_concepts with auto_generate
research_video_concepts(
    concept_description="Wes Anderson symmetrical comedy",
    auto_generate=True  # Research + generate in one call
)

8.列表_视频文件

列出目录中的视频文件，以帮助查找要分析的视频。

参数:

• directory_path （必填）：要搜索的目录的路径
• max_results：要返回的最大文件数（默认值：20）

示例:

list_video_files("/Users/me/Videos")

使用示例

来自克劳德桌面

安装后，您可以在Claude中自然使用这些工具：

User: Analyze this video file at /Users/me/videos/presentation.mp4 
      and tell me what the main topics are.

Claude: [Uses analyze_video_file tool]

User: Now transcribe the audio from that video with timestamps.

Claude: [Uses transcribe_video tool]

User: Compare it to this YouTube video about the same topic:
      https://www.youtube.com/watch?v=example

Claude: [Uses analyze_youtube_video and provides comparison]

程序化使用

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

# Server configuration
server_params = StdioServerParameters(
    command="python",
    args=["gemini_video_mcp.py"],
    env={"GOOGLE_API_KEY": "your-key-here"}
)

async def analyze_my_video():
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            
            # Call the tool
            result = await session.call_tool(
                "analyze_video_file",
                arguments={
                    "video_path": "/path/to/video.mp4",
                    "prompt": "What are the main topics?"
                }
            )
            print(result)

技术细节

帧率采样（FPS）-检测快速场景变化

新增：默认FPS现在为10 以获得最大的场景检测能力。这允许检测短至0.1秒的场景，包括：

• 闪光框架和潜意识切割
• 快速蒙太奇序列
• 快速动作场景
• 快速转换和效果

FPS设置指南:

\*默认分辨率（258个令牌/帧+32个令牌/音频）

何时调整FPS:

• 保持10 FPS （默认）：音乐视频、动作场景、体育、快速蒙太奇、任何快速剪辑的内容
• 低于5 FPS：正常节奏的内容、纪录片、访谈
• 低于3 FPS：慢节奏的内容、演讲人、演示文稿
• 低于1 FPS：非常静态的内容，最大限度地降低成本，或超过1小时的视频

示例:

# Maximum detection for fast-paced video (default)
analyze_video_file(
    video_path="/path/to/action_scene.mp4",
    prompt="Identify all unique shots and scene changes",
    fps=10  # Catches 0.1s scenes
)

# Balanced detection for normal videos
analyze_video_file(
    video_path="/path/to/interview.mp4",
    prompt="Summarize the interview",
    fps=5  # Catches 0.2s scenes, lower cost
)

# Economy mode for long, static content
analyze_video_file(
    video_path="/path/to/lecture.mp4",
    prompt="Extract key points",
    fps=1,  # Minimize token usage
    media_resolution="low"  # Further cost reduction
)

令牌使用情况

视频标记如下（每秒）：

• 默认分辨率:

- 1 FPS：约300个令牌/秒（258个令牌/帧+32个令牌/音频） - 5帧每秒：约1490个令牌（1290个令牌/帧+32个令牌/音频+元数据） - 10 FPS：~2940个令牌/秒（2580个令牌/帧+32个令牌/音频+元数据）

• 低分辨率:

- 1 FPS：约100个令牌/秒（66个令牌/帧+32个令牌/音频） - 5 FPS：约490个令牌/秒（330个令牌/帧+32个令牌/音频+元数据） - 10 FPS：约940个令牌/秒（660个令牌/帧+32个令牌/音频+元数据）

上下文窗口

• Gemini 2.5 Pro（2M背景）:

- 默认分辨率：最多2小时 - 低分辨率：长达6小时

• Gemini 2.5闪光灯（1M背景）:

- 默认分辨率：最多1小时 - 低分辨率：长达3小时

最佳实践

1. 使用正确的输入法:

- 大于20MB或大于1分钟的文件： analyze_video_file - 油管 analyze_youtube_video - 小于20MB的小文件： analyze_inline_video

1. 为您的内容选择合适的FPS:

- 默认10 FPS检测短至0.1秒的场景（最适合动作/快速剪辑） - 在0.2秒的场景中使用5 FPS（对大多数内容进行平衡） - 0.3秒场景使用3 FPS（适用于采访/vlogs） - 静态内容使用1 FPS或将成本降至最低

1. 针对长视频进行优化:

- 使用 media_resolution="low" 节省代币（减少3倍） - 剪辑视频 start_offset 和 end_offset - 静态内容的帧率较低（1-3FPS） - 将两者结合起来以实现最大的节省

1. 时间戳引用:

- 在提示中使用格式“MM:SS”（例如，“02:30时会发生什么？”） - 更高的FPS（5-10）为快节奏视频捕捉更多细节 - 较低的FPS（1-3）足以播放较慢的内容

1. 错误处理:

- 调用前检查文件路径 - 确保YouTube视频公开 - 监控超长视频的令牌使用情况

故障排除

“未设置API_KEY”错误

export GOOGLE_API_KEY="your-key-here"

“找不到文件”错误

• 使用绝对路径而不是相对路径
• 检查文件是否存在： ls -la /path/to/video.mp4

“视频太大”错误

• 使用 analyze_video_file 而不是 analyze_inline_video
• 使用 media_resolution="low" 减少令牌使用
• 用剪辑视频 start_offset 和 end_offset

“无法访问YouTube视频”错误

• 确保视频是公开的（不是私人的或未列出的）
• 检查URL是否正确
• 验证您没有超过每日配额（免费等级为8小时）

“超出上下文窗口”错误

• 使用 media_resolution="low"
• 剪辑到较短的片段
• 使用Gemini 2.5 Pro（2M上下文）代替Flash（1M上下文）

研究缓存管理

research_video_concepts工具缓存研究结果，以减少API调用和成本。

缓存位置: .research_cache/ 目录

缓存持续时间：默认为1周（可配置为 cache_ttl_hours 参数）

管理缓存:

# Using the ResearchCache class directly
from gemini_video_mcp import research_cache

# Clear expired entries (older than 1 week)
research_cache.clear_expired(ttl_hours=168)

# Clear all cache entries
research_cache.clear_all()

# Check cache manually
import json
from pathlib import Path

for cache_file in Path(".research_cache").glob("*.json"):
    with open(cache_file) as f:
        data = json.load(f)
        print(f"Cached: {data['concept']} at {data['timestamp']}")

使用缓存时:

• 相同的概念描述+研究领域=缓存命中
• 无需Google Search API调用即可立即返回研究
• 节省时间并减少API配额的使用

强制进行新的研究:

• 从中删除特定缓存文件 .research_cache/
• 呼叫 research_cache.clear_all() 清除一切
• 等待缓存过期（默认值：1周）

费率限制和定价

• 免费层:

- 每天50个请求 - 每天8小时的YouTube视频

• 付费层：更高的限制，请参阅谷歌人工智能定价

获取API密钥并检查限制，网址：https://aistudio.google.com/apikey

许可证

此MCP服务器按原样提供，以便与Gemini API一起使用。有关API的使用，请参阅Google的服务条款。

贡献

欢迎投稿！拜托：

1. 彻底测试您的更改
2. 遵循现有代码样式
3. 根据需要更新文档
4. 添加新功能的示例

支持

• 问题：请通过GitHub问题报告错误或请求功能
• 文档: https://ai.google.dev/gemini-api/docs/video-understanding
• MCP协议: https://modelcontextprotocol.io/