video-vision-mcp

video-vision-mcp

一个 MCP 服务，让 Claude Code 能够通过一组工具分析任何视频—— 无论是本地文件还是 URL。

Claude 无法原生观看视频（只能读取文本和图像的第一帧）。 此服务会将视频转换为采样帧图像 + 音频转录文本； 如果提供了 Gemini 密钥，还可以对整个视频进行原生 Gemini 分析。

它是独立运行的：提供一个准备好的视频（本地路径或直接 URL），剩下的工作由它完成。它不会连接 Jira/Slack 等服务。如果视频存放在某个集成服务中，请先通过该集成获取视频（下载到文件或获取直接 URL），然后将 file_path 或 url 交给此服务。

场景：某个 Jira 缺陷工单只有屏幕录制，没有文字。你的 Jira MCP 服务将附件下载到临时文件 → analyze_video file_path=/tmp/bug.mp4 → 你会看到视频帧 + 转录文本（或 Gemini 的分析结果），从而能够分析缺陷。

三个后端层级（自动选择）

层级	需要	功能
1 — 本地（默认）	无	使用 ffmpeg 提取视频帧 + 使用 whisper.cpp 转录。免费、完全本地运行，始终可用。
2 — 云端 ASR	OPENAI_API_KEY 或 GROQ_API_KEY	本地提取视频帧，但通过 OpenAI Whisper / Groq 转录，以获得更高质量。
3 — 原生 Gemini	GEMINI_API_KEY	Gemini 通过一次调用处理整个视频（视觉 + 音频），并提供 MM:SS 时间戳。设置密钥后默认使用此层级。

优先级：Gemini > OpenAI > Groq > 本地。 设置 VIDEO_MCP_DISABLE_GEMINI=true 可强制使用层级 1/2，即使已设置 Gemini 密钥。每条结果都会注明所使用的后端。

**隐私：**层级 1 绝不会上传任何内容。层级 2/3 首次向第三方发送视频内容时，会在会话中显示一次性提示。

工具

• analyze_video — 视频帧 + 转录文本 + 元数据（主要工具）。frame_interval 用于设置帧间隔秒数（默认值为 1.0；例如，0.5/0.25/0.1 表示更密集，2/5 表示更稀疏）。
• get_video_transcript_only — 仅获取转录文本。
• extract_frames_at — 提取指定时间戳的帧（"00:42"、"1:05"、12.5）。
• list_recent_analyses — 查看缓存的分析结果及所用后端。

安装

需要 Python ≥ 3.10。一次安装即可获取所有内容，包括后端，以及 ffmpeg 和 whisper.cpp 依赖项。绝不会在你的机器上全局安装任何内容（不使用 brew/apt/winget，也不需要 sudo）。

使用方法（推荐）

使用 uv 时无需显式安装——uvx 会按需运行已发布的软件包（请参阅在 Claude Code 中注册）。若要安装到环境中：

uv pip install video-vision-mcp     # or: pip install video-vision-mcp

从源代码安装（开发）

git clone https://github.com/KitDevUA/video-vision-mcp.git
cd video-vision-mcp
uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"          # all backends bundled

依赖项 — 完全独立

• ffmpeg / ffprobe：如果已位于 PATH 中，则使用系统二进制文件。否则，由捆绑的 static-ffmpeg 软件包提供（仅获取一次并存入其本地缓存，不会进行全系统安装）。
• whisper.cpp（层级 1 转录）：通过捆绑的 pywhispercpp 绑定提供（预构建 wheel；仅当你的平台/Python 没有对应的 wheel 时才会从源代码构建）。如果 PATH 中已有 whisper-cli，则会使用它。
• whisper 模型：首次转录时，会从 Hugging Face 将 ggml 模型（默认为 base）下载到缓存中。可通过 VIDEO_MCP_WHISPER_MODEL（tiny/base/small/medium/large-v3）或 VIDEO_MCP_WHISPER_MODEL_PATH 指定其他模型。
• 仅限云端：设置 OPENAI_API_KEY / GROQ_API_KEY（层级 2）或 GEMINI_API_KEY（层级 3）；此时不会调用 whisper.cpp。

配置

cp env.example .env
# edit .env — nothing is required for tier 1

所有变量见 env.example，全部为可选项（API 密钥和调优参数）。Tier 1 无需任何变量。

在 Claude Code 中注册

将以下内容添加到项目的 .mcp.json（或全局配置）中，示例见 .mcp.json.example：

{
  "mcpServers": {
    "video-vision": {
      "command": "uvx",
      "args": ["video-vision-mcp"],
      "env": { "VIDEO_MCP_ENV": "/abs/path/to/.env" }
    }
  }
}

uvx 会自动下载并运行已发布的软件包，无需手动安装。VIDEO_MCP_ENV 为可选项（Tier 1 无需密钥）；如果使用云端后端，可将其指向你的 .env。 若要基于本地检出的代码进行开发，请改用 "args": ["--from", "/abs/path/to/video-vision-mcp", "video-vision-mcp"]。 重启 Claude Code 后，video-vision 工具便会出现。

缓存

分析结果缓存在 ~/.cache/video-vision-mcp/ 中，缓存键为 （文件哈希值、 后端、帧间隔）。重新分析同一视频会即时完成；切换后端或帧间隔时，各自的结果也会单独保留。下载的视频和 whisper 模型也存放在同一目录中。可通过 VIDEO_MCP_CACHE_DIR 更改缓存目录。

超过 VIDEO_MCP_CACHE_TTL_HOURS （默认值为 24）的缓存分析结果和已下载视频会在启动时清理，读取时也会跳过；将其设为 0 可永久保留。 whisper 模型不会被清理（重新下载的成本较高）。

与集成（例如 Jira、Slack）搭配使用

此服务刻意设计为独立运行，不会与 Jira、Slack 或任何其他服务通信。如果视频位于某个集成服务中，请让该集成的 MCP 获取视频，再将结果传给此服务：

1. 集成 MCP 将附件下载到本地文件（或提供可公开直接访问的 URL；经过身份验证的 API URL 无法与 url 配合使用）。
2. 调用 analyze_video file_path=<downloaded file>（或 url=<direct link>）。

这样，身份验证和特定服务的逻辑就由相应集成处理，而一个视频工具即可服务于所有来源。