Video Research MCP

video-research-mcp

跨录制内容和文档提问，然后检查答案背后的源帧、转录文本和片段。该服务提供 120 个 MCP 工具，用于视频、音频和图像处理、文档分析、网络与学术研究，以及已保存的知识。Agent 工作流会将这些工具组合起来，完成研究或制作任务。

可在 Codex、Claude Code 或任何支持 stdio 模型上下文协议 的客户端中使用。 Gemini 负责主要的分析和研究流程；本地工具用于检查和转换源文件。可选的提供方和运行时可扩展这一核心功能。

打开交互式用户指南（荷兰语）：从你的问题到解决思路。 搜索功能图谱或选择一项任务，查看相应工具、前置条件和步骤。 英文用户文档 还介绍了设置问题和示例。用日常语言在 MCP 客户端中描述你的问题即可开始。

发布版本 · npm · PyPI · 源代码

候选发布版：0.8.0-rc.6（PyPI 0.8.0rc6）。 上述链接指向确切的软件包和不可变的源代码标签。安装前，请查看发布说明以及各流程的前置条件。npm 预发布通道为 next。本次以 API 为先的发布不涉及本地模型评估。稳定版 0.7.1 早于原生 Codex 插件和扩展后的媒体功能。

从源材料到实用结果

工作	可从这些工具开始	检查内容
针对录制内容提问	video_analyze、video_create_session、video_continue_session	源时间戳、答案和支持材料
分阶段分析长录制内容	media_info、video_analyze_windows、job_status	请求的时间区间、试运行计划、执行限制和保留的结果
准备音频或转录文本	audio_transcribe、audio_clip_export、audio_dsp_analyze	字幕或模型来源信息、源时间信息和导出的音频
检查图像或导出媒体	image_read、image_crop、image_ocr、video_frame、video_clip_export	源字节、选定区域或区间、输出文件和清单
比较文档或调查主题	content_analyze、research_document、research_plan、research_web	引用、矛盾之处、缺失的证据和任务状态
生成图像或短视频	独立的说明图像和视频 API	固定的来源、当前操作人员的引述、明确的操作和保存的解码文件；提供方质量尚未通过评估
搜索以往工作	knowledge_ingest、knowledge_search、knowledge_ask	已存储的记录和检索来源信息；需要 Weaviate

例如，向客户端提问：

Compare ~/recordings/design-review.mp4 with ~/docs/requirements.pdf.
Identify decisions that change a requirement. Cite recording timestamps and
relevant document pages, distinguish explicit decisions from interpretation,
and flag anything the sources do not establish.

工作流会组合多个工具；单次 MCP 调用会返回各自的结果。源哈希用于标识字节，导出清单会保留生成产物的方式。模型时间戳、引用和解读仍需对照原始材料核查。对录制内容进行抽样并不能证明已完整覆盖。

安装

你需要 Python 3.11+、uv（客户端的 PATH 中需包含 uvx），以及用于 Gemini 请求的 Gemini API 密钥。安装插件还需要 Node.js 22+ 和 npm。 安装 FFmpeg/FFprobe，用于本地媒体检查、提取帧和导出片段。其他操作可能需要可选依赖或已配置的后端。

默认情况下，服务会依次读取进程环境变量、~/.config/video-research-mcp/.env，然后使用默认值。项目级安装可以选择单独的凭据文件。请将密钥添加到以下路由共用的文件中，并保留已有设置：

GEMINI_API_KEY=your-gemini-api-key

请将文件设为私有（chmod 600 ~/.config/video-research-mcp/.env）。Codex 插件服务接收的环境变量经过筛选，因此该文件是在 Codex 中可靠的凭据配置方式。提供方分析会将源材料发送到已配置的服务，可能产生使用费用。所选分析时间范围不一定会限制上传的文件。

Codex：原生插件

该插件提供 26 个技能和固定版本的研究服务。历史 RC3 观察记录：2026-10-06，在选定的 Codex 0.160.1 RC3 安装中，重新启动全新会话后加载了研究工具和打包的技能。这是历史 RC3 证据。请按照下方的验证步骤检查你安装的版本。原生方式不会运行 Claude 工作流安装程序。

如需全新安装，请将此目录清单保存为 ~/.local/share/video-research-mcp/.agents/plugins/marketplace.json，必要时创建其父目录：

{
  "name": "video-research",
  "interface": { "displayName": "Video Research" },
  "plugins": [
    {
      "name": "video-research",
      "source": {
        "source": "npm",
        "package": "video-research-mcp",
        "version": "0.8.0-rc.6"
      },
      "policy": { "installation": "AVAILABLE", "authentication": "ON_INSTALL" },
      "category": "Productivity"
    }
  ]
}

codex plugin marketplace add ~/.local/share/video-research-mcp
codex plugin add video-research@video-research
codex plugin list --json

启动全新的 Codex 会话。检查 video-research@video-research 是否已启用、其来源是否为 npm 且版本为 0.8.0-rc.6，并确认服务的工具可用。

对于已有安装，请参阅 原生插件和迁移指南。 重新安装前请备份本地插件修改：Codex 会替换其管理的缓存。手动添加的 mcp_servers.video-research 条目可能会隐藏插件服务。在 Codex 0.160.0 上进行的历史 RC1 检查中，即使该条目已禁用也出现了这种情况；指南介绍了需要移除的具体配置。

Claude Code：工作流安装程序

npx [email protected] --global

此操作会将斜杠命令、技能和 Agent 安装到 ~/.claude/，在 ~/.claude.json 中注册研究服务，并在需要时创建凭据模板。设置密钥，重启 Claude Code，然后检查 /mcp。使用 /gr:advisor 选择工作流，或使用 /gr:video、/gr:research 和 /gr:analyze 直接启动。

使用 --local 设置项目范围，并在 ./.config/video-research-mcp/.env 中设置密钥；此方式会替代共用凭据文件的配置方式。使用 --global --check 检查全局安装。更新会保留已修改的工作流文件和自定义配置。有关范围、检查点和回滚，请参阅 安装程序选项和恢复。

其他 MCP 客户端：仅服务

使用客户端的 stdio 注册格式。典型的 JSON 条目如下：

{
  "mcpServers": {
    "video-research": {
      "command": "uvx",
      "args": ["video-research-mcp==0.8.0-rc.6"]
    }
  }
}

此操作会连接相同的工具；Agent 工作流需单独安装。Python 包文件名使用规范化拼写 0.8.0rc6。

验证首次连接

让客户端在不带参数的情况下调用 infra_configure。它会返回正在运行的配置，而不会发起分析请求。然后尝试对你可以自行检查的材料调用一个工具。连接成功可验证设置；检查返回的证据可验证具体结果。

仅配置任务所需内容

设置或附加项	用途
GEMINI_MODEL、GEMINI_FLASH_MODEL	选择受支持的主模型和辅助模型
YOUTUBE_API_KEY	获取 YouTube 元数据、评论和播放列表；否则使用 Gemini 密钥
GEMINI_SESSION_DB	在 SQLite 中持久化视频会话；未设置时使用内存会话
WEAVIATE_URL、WEAVIATE_API_KEY	跨会话存储和检索研究内容
MLFLOW_TRACKING_URI 和 tracing 附加项	跟踪工具执行；设置 GEMINI_TRACING_ENABLED=false 可禁用可选跟踪
LOCAL_FILE_ACCESS_ROOT	将受支持的本地文件操作限制在某个目录中

研究功能无需 Weaviate。配置存储后，写入时发生的错误不会中止流程；如果持久化很重要，请验证存储的记录。 知识库指南 介绍了嵌入、集合和可选查询依赖项。手动配置服务时，添加附加项请保留版本固定，例如 uvx 'video-research-mcp[tracing,agents]==0.8.0-rc.6'。完整的运行时配置见 ServerConfig。

图像编辑、OCR、语音推理、Blender、FreeCAD 和本地模型服务还需要其他运行时或后端支持。安装插件不会安装这些运行时、模型权重或服务提供商账户。使用可选集成前，请查看相应技能及其前置条件。

对于视频制作，独立的 讲解视频配套服务 提供 39 个工具，包括直接通过 HTTP 生成图像和文本或帧视频，以及可选的外部 CLI/渲染流程；场景 Agent 配套服务 提供 两个工具，用于生成场景代码。研究不需要这两者。制作技能还提供旁白、图像生成、片段生成和剪辑的工作流。

生成图像或短视频

单独连接讲解视频配套服务。其 RC4 候选版本（PyPI 上的 0.2.2rc4） 增加了直接通过 HTTP 生成文本到图像、编辑图像、翻译图像，以及根据文本、首帧或首尾帧生成视频的路由。这些路由需要配套服务的 generation 附加项、已有且脚本/场景文件已固定的项目、明确的区域 DashScope 配置，以及最新且已固定的价格/访问和报价声明。视频输出检查还需要 FFmpeg/ffprobe。 这些路由无需上游 video_explainer CLI 即可运行。

请遵循图像生命周期 或视频生命周期。 设置 spend_authorized=true 前，须获得实际人工授权，以便提交源内容并产生费用；该字段仅记录输入确认，不会验证任何人的身份，也不会限制服务提供商的计费额度。请保留返回的任务 ID。 对于已捕获的同步图像，请使用 explainer_image_generation_finalize；对于翻译和明确的图像恢复，请使用 explainer_image_generation_poll；对于视频，请使用 explainer_generation_poll。每次操作都必须有明确授权且限制在有界范围内。核心 job_status 不接受这两种生成媒体任务。

已保存的哈希值和完整解码检查可验证所选文件的字节。实时服务提供商访问、图像身份/风格保真度、创作质量和完整安全审查仍未解决。S2V/HappyHorse 后续模式为可选功能，等待单独的源内容验收；已禁用的原始 Qwen 进程集成为另一条独立路由。素材搜索、本地 ASR 接收时序以及保留的渲染器时序故障仍是限制。

检查与扩展

• 工具实现：精确参数和行为。客户端发现的 MCP 架构描述的是正在运行的版本。
• 分段视频分析：试运行预算、续接、上传限制和保留的部分结果。
• 贡献指南：源代码设置和检查。
• 安全策略：本地访问、提供方边界和问题报告。
• 更新日志：此候选版本中的变更。

所选 RC3 原生检查涵盖了已安装基线和重启，共有 124 个缓存文件。全新通过 npm 网络获取与复用相同版本的缓存之间的差异仍未知。较早的 RC1 原生检查和 RC2 归档／安装程序检查仍为历史结果。工具发现无法验证每个可选运行时；实时提供方的质量和完整的对比验收仍未完成。

---

由 Fausto Albers 创建 · Wonder Why。 基于 Google Gemini、FastMCP 和 Pydantic 构建，并集成了可选的知识和追踪功能。 项目代码采用 MIT 许可证； 第三方声明 涵盖了采用各自条款的捆绑组件。