# video-mcp

让 Codex 和 Claude Code 直接理解 B 站视频：输入一个公开视频链接，本地完成音频下载、语音转写、时间戳索引和按需关键帧提取，再把可引用的视频证据放进对话上下文。

- 不需要 OpenAI、Anthropic 或语音转写 API Key
- 不读取浏览器 cookies；默认只处理无需登录的 B 站公开视频
- 不要求单独安装 pnpm、yt-dlp 或 FFmpeg
- 使用本地 CPU 运行 `faster-whisper`，同一视频的结果会缓存复用
- 通过标准 MCP 同时接入 Codex 和 Claude Code

> 当前版本已在 Windows 上完成真实安装与两种 Agent 的连接验证。macOS/Linux 的安装路径已兼容，但还没有完成同等强度的实机验证。

## 三步开始

### 1. 准备环境

只需要：

- [Git](https://git-scm.com/)
- [Node.js 22+](https://nodejs.org/)
- Python 3.10–3.13（推荐并已验证 Python 3.12）

不需要全局安装 pnpm、yt-dlp、faster-whisper 或 FFmpeg，也不需要 GPU。

### 2. 下载并安装

```powershell
git clone https://github.com/Zoean-z/video-mcp.git
cd video-mcp
npm run setup
```

`npm run setup` 会自动：

1. 在 `.video-agent/runtime/python` 创建项目专用 Python 环境；
2. 安装固定版本的 `faster-whisper` 和 `yt-dlp`；
3. 通过项目固定版本的 pnpm 安装 Node.js 依赖并构建 MCP；
4. 生成本机可用的 `.codex/config.toml` 和 `.mcp.json`。

这些运行时和本机绝对路径配置均被 Git 忽略。重复运行 setup 是安全的。

`ffmpeg-static` 默认从其官方包文档推荐的 `https://cdn.npmmirror.com/binaries/ffmpeg-static` 下载对应平台二进制，避免 B 站主要用户网络下 GitHub Release 过慢。需要改回上游或使用自建镜像时，可在 setup 前设置 `FFMPEG_BINARIES_URL`。

如果自动检测不到 Python：

```powershell
npm run setup -- --python "C:\path\to\python.exe"
```

请在你实际运行 Agent 的同一个环境中执行 setup。例如从 WSL 使用 Claude Code 时，应在 WSL 的仓库和 Python 环境中重新运行，而不是复用 Windows 路径。

### 3. 在 Agent 中使用

#### Codex

安装后重新打开此仓库中的 Codex 任务，并信任项目配置。可以先确认：

```powershell
codex mcp list
```

列表中应出现已启用的 `bilibili-video-mcp`。官方说明：[Codex 项目级配置](https://developers.openai.com/codex/config-reference/)、[Codex MCP](https://developers.openai.com/codex/mcp/)。

#### Claude Code

在仓库根目录启动 Claude Code：

```powershell
claude
```

首次出现项目 MCP 安全提示时批准 `bilibili-video-mcp`，然后可用 `/mcp` 或以下命令检查：

```powershell
claude mcp list
```

官方说明：[Claude Code MCP 项目配置](https://code.claude.com/docs/en/mcp)。

## npm 包状态

`bilibili-video-mcp` 已完成独立 tarball、空目录安装和真实 B 站端到端验证，但目前还没有发布到 npm registry。现在所有人都能使用的稳定路径仍是上面的 Git clone + `npm run setup`；registry 发布后可改用：

```powershell
npm install --global bilibili-video-mcp
video-mcp setup --project "C:\path\to\your-video-workspace"
```

建议持久全局安装或安装到固定项目，不要用一次性的裸 `npx` 路径生成长期 MCP 配置。npm 首次安装会下载当前平台约 83 MB 的 FFmpeg 二进制；网络慢时命令可能数分钟没有新输出，请等待 `npm install` 正常结束。国内网络可在安装前显式使用 `ffmpeg-static` 文档推荐的镜像：

```powershell
$env:FFMPEG_BINARIES_URL = "https://cdn.npmmirror.com/binaries/ffmpeg-static"
npm install --global bilibili-video-mcp
```

`video-mcp setup` 会实际执行 `ffmpeg -version`，不会把仍在下载或不可执行的二进制误报为可用。

## 怎么提问

最简单的请求：

```text
请使用 bilibili-video-mcp 理解这个 B 站视频，等待处理完成后总结核心观点，并给出时间戳证据：
https://www.bilibili.com/video/BV...
```

处理完成后可以在同一对话里持续追问：

```text
作者为什么得出这个结论？
把视频里支持和反对这个观点的内容分别列出来。
结合关键画面判断这段话是在展示数据，还是只表达个人意见。
```

转写内容不超过 20,000 个紧凑字符时，Agent 可以直接把整篇带时间戳转写放入上下文；更长的视频会先搜索相关片段，再读取邻近语境。正常的视频总结还会按需提取至少三个重要时间段的关键帧，因此不仅依赖音频。重复提问不会重新转写已经缓存的视频。

## 它在本机做了什么

```text
B 站 URL
  -> yt-dlp 匿名探测与音频下载
  -> faster-whisper CPU 转写
  -> 完整转写文件 + SQLite 时间戳证据索引
  -> MCP 将完整转写或相关片段注入 Agent 上下文
  -> 需要验证画面时，仅下载相关的 1–120 秒区间并提取关键帧
```

MCP 暴露 8 个工具和 1 个摘要 prompt：

- `probe_video`：不下载媒体，先检查公开视频信息；
- `submit_ingest`：后台下载音频、转写并建立索引；
- `get_ingest_status`：读取后台任务阶段、进度或错误；
- `get_video_transcript`：在大小允许时返回整篇带时间戳转写；
- `search_video`：搜索转写数据库中的相关证据；
- `get_video_segment`：读取某个命中片段及邻近语境；
- `get_video_context`：生成有字符上限、适合直接注入对话的证据块；
- `get_video_frames`：获取相关短区间的 1–3 张 JPEG 关键帧；
- `summarize_video`：要求基于证据、引用时间戳并核对关键画面的摘要流程。

## 本地数据与安全

- 视频音频、转写、索引、任务状态和关键帧保存在仓库下的 `.video-agent/`，不会上传到本项目自建服务；
- MCP 会把被调用工具的结果交给当前 Agent，所以你使用的 Codex/Claude 服务仍可能接收这些上下文；
- 当前不会读取浏览器 cookies，也不会尝试绕过登录、付费、地区或权限限制；
- 视频标题、字幕、语音转写和画面文字都按“不可信数据”处理，不应被当成 Agent 指令执行；
- `.codex/config.toml` 和 `.mcp.json` 会启动当前仓库中的本地代码，请只在你审查并信任仓库后批准。

## 已知限制

- 当前只支持 B 站 URL，并优先保证无需登录的公开视频；
- ASR（自动语音识别）对人名、游戏术语、方言和背景音乐中的讲话可能识别不准；
- 第一次转写某个模型时，`faster-whisper` 会额外下载开源模型；CPU 转写长视频需要等待；
- 第一次 setup 还会下载当前平台的 FFmpeg 二进制，速度取决于网络；
- 画面分析采用“转写定位后按需取关键帧”，不是逐帧理解整段视频；
- 默认模型为 `base`，也支持更快的 `tiny` 和更准确但更慢的 `small`。

## 排查

### Agent 中找不到 `bilibili-video-mcp`

在仓库根目录重新运行：

```powershell
npm run setup
codex mcp list
claude mcp list
```

然后重启 Codex 任务，或在 Claude Code 中运行 `/mcp`。Claude Code 对项目 `.mcp.json` 的拒绝记录可用 `claude mcp reset-project-choices` 重置。

### 安装或转写失败

不要在不同 Python 环境之间混装依赖。先重新执行 setup；它会验证同一个项目 Python 是否能同时导入 `yt_dlp` 和 `faster_whisper`：

```powershell
npm run setup -- --python "C:\path\to\python.exe"
```

后台任务、转写或画面已缓存时，Agent 会从最近成功的 artifact 继续，而不是从头重复处理。

## 开发

完成 setup 后：

```powershell
pnpm typecheck
pnpm test
pnpm build
pnpm probe "https://www.bilibili.com/video/BV1e3411j7ZM" --pretty
pnpm ingest "https://www.bilibili.com/video/BV1e3411j7ZM" --model base --pretty
```

转写 artifact 路径：

```text
.video-agent/artifacts/<videoId>/p<part>/transcript.<model>.json
```

证据索引默认位于 `.video-agent/catalog.db`。同一视频、分 P 和模型组合会校验并复用已有音频与转写。

## License

[MIT](LICENSE) © 2026 Zoean-z