Gemini Video Understanding Skill - 让 Claude Code 理解视频内容

本文介绍 MCP Gemini Video Understanding，一个基于 Google Gemini API 的 MCP (Model Context Protocol) 服务器，用于分析视频内容并将其转换为 Claude Code 可理解和处理的文本描述。

项目简介

MCP Gemini Video Understanding 是一个开源的 MCP 服务器，作为视频内容与 Claude Code 之间的桥梁。当你有视频（屏幕录制、Loom 视频、YouTube 教程等）时，该服务器利用 Gemini 强大的视频理解能力，提取有意义的文本描述，供 Claude Code 编写代码、修复错误或实现功能。

GitHub 仓库：https://github.com/ugarchance/mcp-gemini-video-understanding

核心功能

• Bug 视频分析：录制展示错误的视频 → 获取详细的复现步骤和调试见解
• 设计原型分析：在视频中展示设计 → 获取 UI 组件分解的实现指导
• YouTube 教程解析：分享教程 URL → 提取关键学习点和实现步骤
• 响应式问题诊断：录制布局问题 → 获取特定的 CSS 修复和响应式解决方案

技术栈

• Node.js/TypeScript：核心开发语言
• Google Gemini API：视频理解能力
• Model Context Protocol (MCP)：与 Claude Code 集成
• Gemini File API：处理大文件（>20MB）

安装指南

全局安装

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

使用 npx（无需安装）

npx @ugarchance/mcp-gemini-video-understanding

快速开始

1. 获取 Gemini API Key

• 访问 Google AI Studio
• 点击 "Get API Key"
• 创建或选择项目
• 复制你的 API key

2. 设置环境变量

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

3. 配置 Claude Code

编辑 claude_desktop_config.json：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %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"
      }
    }
  }
}

使用示例

分析 Bug 视频

我有一个 bug 视频在 /Users/me/Desktop/bug-demo.mp4
保存分析结果到 bug-analysis.md 并修复问题。

分析设计原型

我录制了一个设计原型在 /Users/me/Desktop/new-feature.mp4
保存分析结果到 design-spec.md，然后用 React 和 Tailwind CSS 实现。

分析 YouTube 教程

观看这个教程：https://www.youtube.com/watch?v=xxxxx
保存学习笔记到 tutorial-notes.md，然后实现认证系统。

支持的视频格式

• MP4
• MOV
• AVI
• WebM
• MKV
• FLV
• WMV
• 3GP
• MPEG

可用模型

缓存策略

当指定 output_file 时：

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

这非常适合：迭代实现而不重新分析视频、与团队成员共享分析结果、降低 API 成本和延迟。

限制说明

• YouTube：仅支持公开视频（不支持私密或未列出）
• 文件大小：>20MB 的文件自动使用 Gemini 的 File API（处理时间可能更长）
• 视频长度：较长的视频需要更多处理时间
• 速率限制：受 Gemini API 速率限制
• 缓存：仅在使用 output_file 时有效

开发指南

本地开发

# 克隆仓库
git clone https://github.com/ugarchance/mcp-gemini-video-understanding
cd mcp-gemini-video-understanding

# 安装依赖
npm install

# 构建
npm run build

# 本地测试（添加到 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

# 更新 package.json 中的 npm 用户名
npm login
npm publish

故障排除

"GEMINI_API_KEY environment variable is required"

确保已在 claude_desktop_config.json 的 env 部分设置 GEMINI_API_KEY。

"Error analyzing video"

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

工具未在 Claude Code 中显示

• 完全重启 Claude Code（Mac 上 Cmd+Q，不只是关闭窗口）
• 检查 claude_desktop_config.json 语法是否为有效 JSON
• 查看 Claude Code 日志：~/Library/Logs/Claude/mcp*.log (macOS)

许可证

MIT License

相关链接

• GitHub 仓库：https://github.com/ugarchance/mcp-gemini-video-understanding
• SkillsMP 页面：https://skillsmp.com/skills/huydepzai121-skill-claude-skills-gemini-video-understanding-skill-md
• Google AI Studio：https://aistudio.google.com/