VidXP MCP Server

找到那一刻，而不是时间戳

VidXP 让单个视频——或整个视频集——可以按含义进行搜索：

• **对话搜索：**输入你记得某人说过的话，即可跳转到匹配的时刻。

• **场景搜索：**描述屏幕上出现的内容，找到最接近的视觉匹配。

• **动作搜索：**描述在几秒钟内发生的事情。

• **演员匹配：**找出视频中反复出现的面孔，并为选定的一组导出高亮视频。

你可以用它搜索多年的家庭视频、为剪辑工作流添加视频搜索，或者让 AI 代理利用你自己的视频库中的证据来回答问题。你的视频可以始终留在自己的机器上。

Related MCP server: klaket-mcp

从这里开始

选择最适合你使用 VidXP 的安装方式。

1. 桌面应用

从 GitHub Releases 下载适用于 Windows、Apple Silicon macOS 或 Linux 的安装程序。

你可以连接现有的 VidXP 安装，也可以让桌面应用为你管理一个独立的运行时。支持的安装选项请参阅桌面应用安装说明。

2. CLI 和本地 AI 助手

对于命令、脚本和本地 AI 助手，请先安装 uv，然后运行：

# Install the CPU edition
uv tool install --python 3.14 --torch-backend cpu "vidxp[local-worker,mcp]"

# Check FFmpeg, download models, and verify the installation
vidxp init
vidxp prepare
vidxp doctor

# Print the settings for a local MCP client
vidxp mcp-config

通过以下命令添加浏览器界面：

uv tool install --python 3.14 --torch-backend cpu \
  "vidxp[local-worker,mcp,frontend]"
vidxp ui

有关特定客户端的 MCP 配置、HTTP API 和远程服务器设置，请参阅安装指南。

3. 用于服务器的 Docker

在家庭服务器或其他单台机器上运行已发布的一体化镜像：

# Download the search models into the persistent volume
docker run --rm -it \
  -v vidxp-data:/var/lib/vidxp \
  ghcr.io/grayhatdevelopers/vidxp:latest \
  vidxp prepare

# Start the browser interface
docker run --rm --init \
  -p 8501:8501 \
  -v vidxp-data:/var/lib/vidxp \
  ghcr.io/grayhatdevelopers/vidxp:latest

对于长期运行的服务器，请固定到已发布的版本，而不是使用 latest。对于 Coolify 部署，请使用已发布的 -control 和 -worker 镜像配合 compose.coolify.yaml——无需从仓库构建。完整的设置请参阅 Coolify 指南。

你现在可以做什么

• 从单个视频或整个视频集构建可搜索的资料库。

• 通过描述查找对话、声音事件、视觉场景和多帧动作。

• 提出有据可依的问题，并检查支撑性的看板、帧或片段。

• 对反复出现的面孔进行分组，并渲染高亮的演员叠加层。

• 将个人、客户或项目的资料库分开保存。

• 通过桌面应用、浏览器、CLI、MCP 或 HTTP API 使用 VidXP。

第一次搜索

浏览器应用会引导你完成导入和索引。在命令行中执行同样的流程如下：

# Add a video
vidxp media import samplevideo.mp4 --json

# Index the returned media ID
vidxp index create <media-id>

# Find a visual moment
vidxp search scene "a yellow taxi on a city street"

# Find an action or event
vidxp search videoprism "a person opens a door and walks outside"

# Find a sound event
vidxp search sound "a dog barking over traffic noise"

# Find something that was said
vidxp search dialogue "the bread just came out of the oven"

结果包括源视频、时间戳、匹配分数，以及用于找到那一刻的证据。添加 --media-id <media-id> 可只搜索单个视频。

运行 vidxp --help 或 vidxp <command> --help 可查看完整的命令参考。

面向应用程序和 AI 代理

使用 Python 包将选定的 VidXP 功能直接集成到应用程序中，或者在 VidXP 作为服务运行时使用 HTTP API。

MCP 让 AI 客户端可以添加和索引视频、搜索资料库、提出有据可依的问题，并返回可检查的证据，例如看板、帧和片段。本地客户端可以在同一台计算机上以程序方式启动 VidXP。托管客户端则连接到已部署的 VidXP 服务器。

Codex 插件与技能

VidXP 通过托管在本 GitHub 仓库中的 Git 市场以 Codex 插件的形式分发。它包含三个可复用的工作流：

• 安装桌面版或 CLI 并连接 Codex；

• 摄取并索引视频；

• 找到关键时刻并返回可检查的证据。

将以下内容粘贴到 Codex 中：

Add https://github.com/grayhatdevelopers/vidxp as a Git plugin marketplace, install the VidXP plugin, then use its $vidxp-install skill to set up VidXP on this computer.

VidXP 桌面版可以通过其 在 Codex 中设置 按钮完成同样的设置。

兼容的 AI 客户端可以显示交互式的上传和证据查看视图。没有该界面的客户端仍然可以通过普通的 MCP 工具获得相同的工作流结果。

• Python、HTTP 和 MCP 安装

• 本地 HTTP API 和 MCP 服务器

• ChatGPT 和 Codex 插件集成

• 可选功能包

• Coolify 服务器设置

下载与存储

首次设置只会下载你所选功能所需的模型。VidXP 会在开始下载前显示下载大小和目标位置。

由桌面版管理的 Python 运行时及其选定的依赖项大约占用 3 GiB。

包含所有搜索功能的完整本地桌面版安装大约占用 9.0 GiB。请在安装期间留出额外的临时空间，并为索引、源视频和导出结果预留空间。

默认情况下，CLI 和桌面应用共享同一个 VidXP 数据目录：

Docker 会将相同的数据保存在上面所示的 vidxp-data 卷中。

产品路线图

接下来的产品改进将聚焦于：

• 为演员分组添加标签，并在不同视频中匹配同一个人；

• 在角度、光照、运动和遮挡情况下进行更可靠的人脸跟踪；

• 将画面中可见的人物与其正在说的对话关联起来；

• 更好的搜索排序、时间范围，以及跨整个资料库的自然语言提问；

• 更丰富的预览、时间线、筛选器、已保存的搜索和结果回放；

• 更方便地整理大型个人和项目视频收藏；

• 更快的索引以及支持的 GPU 加速；以及

• 更流畅的桌面版更新、修复和模型管理。

VidXP 目前处于测试阶段。关于搜索质量、演员工作流和真实视频库使用案例的反馈尤其有用。

帮助与项目链接

• 安装与故障排查

• 桌面版开发

• Coolify 部署

• 更新日志

• 问题跟踪器

• MIT 许可证

参与贡献

欢迎贡献。在提交拉取请求之前，请阅读贡献指南。

致谢

VidXP 最初是以下学生的研究项目：

• Abdullah Mansoor

• Muhammad Haroon

• Sarah Jawaid

• Talha Ahmed

这项研究是与 NED University of Engineering and Technology 的 Dr Shahab Tahzeeb 以及 Grayhat 的 Saad Bazaz 合作完成的。

VidXP 现在由 Grayhat 开发，并由社区贡献者维护。

邮箱：info@grayhat.studio