AI导哈

视频理解服务

一个使用Google Gemini API分析视频并将其转换为Claude Code可理解的文本描述的MCP服务器。

  • by ugarchance
  • JavaScript
  • 本地部署
  • 更新于
在 GitHub 查看 ugarchance/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
  • 动态图像专家组

可用模型

|型号|速度|质量|性价比| |-------|-------|---------|----------|------| | gemini-2.5-pro |缓慢|最高|复杂的错误，详细的设计|$$$| | gemini-2.5-flash | 快速 | 高 | 一般用途（默认） | $$ | | gemini-2.5-flash-lite |最快|良好|快速摘要，简单视频|$| | gemini-2.0-flash |快速|良好|上一代，可靠|$$| | gemini-2.0-flash-exp |快速|变化|实验功能|$$|

局限性

  • 油管：仅公开视频（非私人或未列出）
  • 文件大小：大于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。

鸣谢

内置：

相关 MCP