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

• Node.js 22+

• Python 3.10–3.13（推荐并已验证 Python 3.12）

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

2. 下载并安装

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：

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

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

3. 在 Agent 中使用

Codex

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

codex mcp list

列表中应出现已启用的 bilibili-video-mcp。官方说明：Codex 项目级配置、Codex MCP。

Claude Code

在仓库根目录启动 Claude Code：

claude

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

claude mcp list

官方说明：Claude Code MCP 项目配置。

Related MCP server: Bilibili API MCP Server

npm 包状态

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

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 文档推荐的镜像：

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

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

怎么提问

最简单的请求：

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

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

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

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

它在本机做了什么

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

在仓库根目录重新运行：

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：

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

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

开发

完成 setup 后：

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 路径：

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

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

License

MIT © 2026 Zoean-z