MCP Gemini Video Understanding

MCP Gemini视频理解

一个MCP（模型上下文协议）服务器，使用谷歌的Gemini API来分析视频，并将其转换为Claude Code可以理解和执行的文本描述。

这是什么？

此MCP服务器充当视频内容和Claude Code之间的桥梁。当您有视频（屏幕录制、Loom视频、YouTube教程等）时，此服务器使用Gemini强大的视频理解功能来提取有意义的文本描述，然后Claude Code可以使用这些描述来编写代码、修复错误或实现功能。

用例

1. Bug复制视频：录制一段显示错误的视频→ 获取再现和调试见解的详细步骤
2. 设计模型：在视频中展示设计→ 通过UI组件分解获得实施指导
3. YouTube教程：共享教程URL→ 提取关键经验教训和实施步骤
4. 响应性问题：记录布局问题→ 获取特定的CSS修复和响应式解决方案

安装

npm install -g @ugarchance/mcp-gemini-video-understanding

或直接与 npx:

npx @ugarchance/mcp-gemini-video-understanding

设置

1.获取Gemini API密钥

1. 首选 谷歌人工智能工作室
2. 点击“获取API密钥”
3. 创建或选择项目
4. 复制API密钥

2.设置环境变量

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

3.配置克劳德代码

添加到您的 claude_desktop_config.json:

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

{
  "mcpServers": {
    "gemini-video": {
      "command": "npx",
      "args": [
        "-y",
        "@ugarchance/mcp-gemini-video-understanding"
      ],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

或者，如果全局安装：

{
  "mcpServers": {
    "gemini-video": {
      "command": "mcp-gemini-video",
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

用法

所有工具都支持这些常见参数：

• model （字符串，可选）：双子模型使用。选项：

- gemini-2.5-pro -能力最强，最适合复杂分析 - gemini-2.5-flash - 默认，速度和质量平衡 - gemini-2.5-flash-lite -最快、最轻的分析 - gemini-2.0-flash -上一代快速模型 - gemini-2.0-flash-exp -实验特征

• output_file （字符串，可选）：保存分析的路径。若文件存在，则使用缓存结果（无需重新分析！）

工具1：分析\_ bug \_视频

分析显示错误或错误的视频。

参数:

• video_path （string）：视频文件或YouTube URL的路径
• is_youtube （布尔值，可选）：设置为 true 如果使用YouTube URL
• additional_context （string，可选）：关于bug的额外上下文
• model （字符串，可选）：使用Gemini模型
• output_file （字符串，可选）：保存分析的路径

克劳德代码示例:

I have a bug video at /Users/me/Desktop/bug-demo.mp4
Save the analysis to bug-analysis.md and fix the issue.

通过型号选择:

Analyze /Users/me/Desktop/complex-bug.mp4 using gemini-2.5-pro
Save to analysis.txt and help me fix it.

工具2：分析_设计_视频

分析显示设计模型或功能演示的视频。

参数:

• video_path （string）：视频文件或YouTube URL的路径
• is_youtube （布尔值，可选）：设置为 true 如果使用YouTube URL
• tech_stack （字符串，可选）：要使用的技术（例如，“与顺风反应”）
• model （字符串，可选）：使用Gemini模型
• output_file （字符串，可选）：保存分析的路径

克劳德代码示例:

I recorded a design mockup at /Users/me/Desktop/new-feature.mp4
Save analysis to design-spec.md then implement using React and Tailwind CSS.

工具3：分析_教程_视频

分析YouTube教程以提取关键知识。

参数:

• video_url （字符串）：YouTube URL
• focus_area （字符串，可选）：要关注的特定主题
• model （字符串，可选）：使用Gemini模型
• output_file （字符串，可选）：保存分析的路径

克劳德代码示例:

Watch this tutorial: https://www.youtube.com/watch?v=xxxxx
Save the learnings to tutorial-notes.md then implement the auth system.

使用更快的模型进行快速摘要:

Analyze https://www.youtube.com/watch?v=xxxxx with gemini-2.5-flash-lite
Just give me the key points.

工具4：分析_响应_问题

分析显示响应式设计问题的视频。

参数:

• video_path （string）：视频文件或YouTube URL的路径
• is_youtube （布尔值，可选）：设置为 true 如果使用YouTube URL
• target_devices （字符串，可选）：目标设备（例如，“移动设备、平板电脑”）
• model （字符串，可选）：使用Gemini模型
• output_file （字符串，可选）：保存分析的路径

克劳德代码示例:

I recorded responsive issues at /Users/me/Desktop/mobile-issues.mp4
Save analysis to responsive-fixes.md and fix the layout for mobile.

运作原理

1. 你 录制视频或查找YouTube URL
2. 你 让Claude Code通过MCP进行分析（可选地指定模型和输出文件）
3. MCP服务器 检查缓存分析是否存在（如果 output_file 指定）
4. 如果没有缓存：向Gemini API发送选定型号的视频
5. 双子座 分析视频并返回详细的文本描述
6. MCP服务器 将结果保存到文件（如果 output_file 指定）
7. 克劳德代码 接收文本，现在可以根据它编写/修复代码

缓存策略

当您指定 output_file:

• 首次运行：分析视频并将结果保存到文件中
• 后续运行：缓存文件立即读取（无需API调用，无需任何成本！）
• 重新分析：首先删除输出文件

这非常适合：

• 在不重新分析视频的情况下迭代实现
• 与团队成员共享分析结果
• 降低API成本和延迟

支持的视频格式

• 四个
• MOV
• 音频视频交错
• WebM
• MKV
• FLV
• WMV
• 3GP
• 动态图像专家组

可用模型

局限性

• 油管：仅公开视频（非私人或未列出）
• 文件大小：大于20MB的文件自动使用Gemini的文件API（处理可能需要更长时间）
• 视频长度：较长的视频需要更多的时间来处理
• 速率限制：受双子星API价格限制
• 缓存：仅在以下情况下有效 output_file 已指定

发展

地方发展

# Clone the repo
git clone https://github.com/ugarchance/mcp-gemini-video-understanding
cd mcp-gemini-video-understanding

# Install dependencies
npm install

# Build
npm run build

# Test locally with Claude Code
# Add to claude_desktop_config.json:
{
  "mcpServers": {
    "gemini-video": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-gemini-video-understanding/build/index.js"],
      "env": {
        "GEMINI_API_KEY": "your-key"
      }
    }
  }
}

发布到npm

# Update package.json with your npm username
npm login
npm publish

故障排除

“需要GEMINI_API_KEY环境变量”

确保您已设置 GEMINI_API_KEY 在你的 claude_desktop_config.json 在...之下 env 部分。

“分析视频时出错”

• 检查视频文件路径是否为绝对路径（而非相对路径）
• 验证是否支持视频格式
• 对于YouTube视频，请确保URL有效且视频是公开的
• 检查Gemini API配额和费率限制

Claude代码中未显示工具

1. 完全重新启动Claude Code（Mac上的Cmd+Q，而不仅仅是关闭窗口）
2. 检查 claude_desktop_config.json 语法是有效的JSON
3. 查看Claude代码日志： ~/Library/Logs/Claude/mcp*.log （macOS）

许可证

麻省理工学院

贡献

欢迎投稿！请打开问题或PR。

鸣谢

内置：

• API双子星 用于视频理解
• 模型上下文协议 克劳德整合