Video Understanding MCP

视频理解 MCP

一个 MCP 服务，可让 AI Agent 观看视频并回答相关问题：画面中有什么、视频里说了什么、屏幕上出现了哪些文字，以及这些内容出现的时间。它适用于任何与 OpenAI 兼容、且模型支持视频的聊天补全端点，例如通过网关提供服务的 Gemini 模型。

提供 TikTok、YouTube 或 X 帖子网址、抓取工具返回的直接媒体网址，或本地文件，并附上问题。它会下载并压缩视频，将其发送到你的端点，然后返回结构化答案：

{
  "answer": "The coach demonstrates three squat variations and warns against letting the knees cave in.",
  "summary": "A short workout tutorial showing bodyweight squats with form cues.",
  "speech": {
    "present": true,
    "language": "en",
    "transcript": "Keep your chest up and push through your heels..."
  },
  "on_screen_text": ["3 x 12 reps", "Rest 60s"],
  "timeline": [{ "start": 12.0, "description": "Switches to jump squats" }],
  "analysis": {
    "configuredModel": "your-model",
    "reportedModel": "gemini-...",
    "usage": { "promptTokens": 5400, "completionTokens": 480 },
    "sourceDurationSeconds": 58.4,
    "analyzedRange": { "start": 0, "end": 58.4 },
    "partFormat": "image_url",
    "warnings": []
  }
}

要求

• Node.js 22.21.0 或更高版本。
• ffmpeg 和 ffprobe（必需）。macOS：brew install ffmpeg。Debian/Ubuntu：sudo apt-get install ffmpeg。Windows：winget install ffmpeg。
• yt-dlp（可选，仅在处理 TikTok 或 YouTube 等页面网址时需要）。macOS：brew install yt-dlp。其他系统：pipx install yt-dlp。
• 与 OpenAI 兼容的端点，以及支持视频输入的模型。

使用 get_server_info 工具查看服务发现的信息。

设置

将此服务添加到你的 MCP 客户端。例如，在使用 JSON 配置的客户端中：

{
  "mcpServers": {
    "video-understanding": {
      "command": "npx",
      "args": ["-y", "@granitebps/video-understanding-mcp"],
      "env": {
        "VIDEO_BASE_URL": "https://your-endpoint.example/v1",
        "VIDEO_MODEL": "your-video-capable-model",
        "VIDEO_API_KEY": "your-endpoint-api-key"
      }
    }
  }
}

服务也会从其工作目录读取 .env 文件。请参阅 .env.example。

工具

understand_video

输入	说明
source	必需。页面网址（通过 yt-dlp 解析）、直接媒体网址，或允许目录中的绝对本地路径。
headers	可选。直接媒体网址的请求标头，例如抓取工具返回的 Referer 或 Cookie。这些标头只会发送到该网址所属的主机。
question	可选。要了解的内容。不提供时，将返回一般性描述。
start_seconds、end_seconds	可选。要分析的源视频时间范围。视频超过时长限制时必须提供；较短的范围也有助于更详细地分析锻炼等快速运动场景。
fps	可选的帧采样提示，仅适用于支持该设置的请求格式。

结果字段如上所示。即使分析了指定范围，timeline 中的时间也表示从源视频开头起算的秒数。analysis.warnings 会说明服务调整了哪些内容，或哪些内容无法确认。

get_server_info

显示版本、端点主机和模型、请求格式、限制、本地文件策略，以及 ffmpeg、ffprobe 和 yt-dlp 是否可用。它不会显示 API 密钥。

请求格式

兼容 OpenAI 的端点在如何将视频附加到聊天请求方面并不一致，有些端点还会静默忽略不支持的格式。请通过 VIDEO_PART_FORMAT 选择端点文档中注明的格式：

VIDEO_PART_FORMAT	请求部分	已知使用该格式的服务
video_url	{"type":"video_url","video_url":{"url":"data:video/mp4;base64,..."}}	OpenRouter、Alibaba Model Studio（Qwen）、Tencent TokenHub、vLLM
image_url (default)	{"type":"image_url","image_url":{"url":"data:video/mp4;base64,..."}}	OpenRouter；会根据数据 URL 的 MIME 类型转换图像部分的路由器，例如 9router 的 Gemini 路径
file	{"type":"file","file":{"file_data":"data:video/mp4;base64,...","format":"video/mp4"}}	LiteLLM（Gemini、vLLM）
input_file	{"type":"input_file","file_data":"data:video/mp4;base64,...","mime_type":"video/mp4"}	Requesty

fps 仅随 video_url 和 file 发送。

如果端点忽略了视频，调用会失败并返回 MEDIA_NOT_PROCESSED，而不是返回模型编造的答案。服务会通过并行发送一条不含视频的相同提示词（最多生成 16 个输出词元），并比较提示词词元用量来检测这一情况；这样可以抵消端点增加的任何固定开销。这会使请求数量翻倍。只有在端点报告的词元用量异常时，才使用 VIDEO_VERIFY_MEDIA=false 关闭此功能。

配置

变量	默认值	描述
VIDEO_BASE_URL	—	必填。端点基础 URL，例如 https://host/v1。
VIDEO_MODEL	—	必填。模型名称或路由别名。
VIDEO_API_KEY	—	作为 Authorization: Bearer <key> 发送。
VIDEO_PART_FORMAT	image_url	image_url、video_url、file 或 input_file。
VIDEO_MAX_DURATION_SECONDS	300	分析范围的最长时长（1–7200）。
VIDEO_MAX_UPLOAD_MB	15	内联发送的预处理视频最大大小，未进行 base64 编码前计算（1–100）。
VIDEO_MAX_DOWNLOAD_MB	500	源文件下载的最大大小（1–10000）。
VIDEO_REQUEST_TIMEOUT_MS	180000	端点请求超时时间（5000–900000）。
VIDEO_MAX_CONCURRENCY	2	同时运行的分析数；后续调用将等待（1–16）。
VIDEO_MAX_OUTPUT_TOKENS	8192	答案的 max_tokens（256–65536）。
VIDEO_VERIFY_MEDIA	true	如果端点明显忽略了视频，则调用失败。
VIDEO_ALLOWED_DIRS	—	允许读取本地文件的目录，以 : 分隔（Windows 上使用 ;）。未设置时将拒绝读取本地文件。
VIDEO_ALLOW_PRIVATE_NETWORK	false	允许从环回地址和专用地址下载。
VIDEO_FFMPEG_PATH	ffmpeg	ffmpeg 可执行文件。
VIDEO_FFPROBE_PATH	ffprobe	ffprobe 可执行文件。
VIDEO_YTDLP_PATH	yt-dlp	yt-dlp 可执行文件。

无效值会导致服务在启动时停止，并显示指出变量名称的消息。缺少 VIDEO_BASE_URL 或 VIDEO_MODEL 时，服务仍会启动，而 understand_video 会返回 CONFIG_MISSING。

调用过程

1. 检查配置、ffmpeg 是否已安装，以及基础 URL 是否有响应。如果没有响应，调用会在下载任何内容之前以 ENDPOINT_UNREACHABLE 失败。
2. 获取视频：读取获准的本地文件、下载直接媒体 URL，或使用 yt-dlp 解析页面 URL（下载前会拒绝时长过长的视频）。
3. 剪切所请求的范围，并将其重新编码为 H.264，音频采用单声道 AAC，较短边最长为 480 像素（竖屏片段为 480×854）；如果需要，会降至 360 像素以符合上传限制。
4. 将视频以内联 base64 格式连同问题一起发送，并发送纯文本基线请求。
5. 验证回复，丢弃分析范围之外的时间轴片段，并将时间转换为源视频中的秒数。

每次调用后都会删除临时文件，包括失败和取消的调用。

错误

错误以方括号中的代码开头，例如 [LIMIT_EXCEEDED] The analyzed range is 1500 s, over the 300 s limit ...，并在 _meta["video-understanding-mcp/error"] 中携带相同的代码。

代码	含义
INVALID_INPUT	范围或来源字符串无效。
CONFIG_MISSING	未设置 VIDEO_BASE_URL 或 VIDEO_MODEL。
DEPENDENCY_MISSING	未安装 ffmpeg/ffprobe，或页面 URL 所需的 yt-dlp。
SOURCE_UNAVAILABLE	无法获取或提取页面或媒体 URL（链接已过期、网站不受支持）。
SOURCE_NOT_ALLOWED	本地文件位于允许目录之外，或下载目标位于专用网络上。
INVALID_MEDIA	来源不包含视频流。
LIMIT_EXCEEDED	超出时长、上传或下载限制，或端点因内容过大而拒绝请求。
ENDPOINT_UNREACHABLE	无法访问配置的基础 URL。
ENDPOINT_AUTH	端点拒绝了 API 密钥。
ENDPOINT_RATE_LIMITED	端点对请求进行了速率限制；如果已知，则会设置 retryAfterSeconds。
ENDPOINT_ERROR	其他任何端点错误，包括成功状态下返回的错误。
TIMEOUT	端点或媒体处理步骤耗时过长。
EMPTY_RESPONSE	模型未返回任何文本。
MEDIA_NOT_PROCESSED	端点显然忽略了视频；请尝试其他 VIDEO_PART_FORMAT。
INTERNAL_ERROR	意外故障。

隐私与内容权利

• 分析的片段和问题会发送到你配置的端点。请使用你认可其数据处理方式的端点。
• 你有责任确保有权下载和分析所提交的内容，并遵守下载内容所在网站的条款。
• 日志以每次调用一行 JSON 的形式写入 stderr（代码、来源主机、时长、大小、计时、令牌数）。日志绝不包含媒体、转录文本、答案、带查询字符串的 URL、标头或 API 密钥。

安全

• 除非设置 VIDEO_ALLOW_PRIVATE_NETWORK=true，否则下载会拒绝回环、私有、链路本地及其他非公开地址，包括重定向目标。端点本身可以位于本地地址。
• 本地文件仅会从 VIDEO_ALLOWED_DIRS 中读取，并且会先解析符号链接。
• 调用方提供的标头只会发送到原始主机，绝不会传递给 yt-dlp。
• ffmpeg 和 ffprobe 只会将输入作为本地文件打开，并且会拒绝 HLS 等播放列表或拼接格式。yt-dlp 会使用 --ignore-config 运行。

如需报告漏洞，请参阅 SECURITY.md。

已知限制

• 视频会以内联方式随请求发送，因此每次调用都受上传限制约束。对于长视频，请使用 start_seconds 和 end_seconds；服务不会自动拆分视频。
• 对于页面 URL，网络限制只会检查页面主机。yt-dlp 会自行向媒体服务器发起后续请求。
• 当路由器在不同提供商之间回退时，基线请求和实际请求可能由固定开销不同的提供商处理，因此忽略视频检查可能会产生误判。analysis.reportedModel 会显示实际响应的模型。
• 除端点报告的模型名称外，无法得知请求由哪个上游提供商处理。
• 仅提供 stdio 传输方式。

开发

npm ci
npm run check

npm run check 会运行格式检查、lint、类型检查、带覆盖率的测试以及软件包检查。测试使用虚假端点、虚假 yt-dlp 和由 ffmpeg 生成的片段，因此需要 ffmpeg，但不需要网络或凭据。npm run test:live 会使用 VIDEO_LIVE_* 变量配置的真实端点运行可选检查（参见 .env.example）。

请参阅 CONTRIBUTING.md 和 RELEASE.md。

许可证

MIT