VIDEO-TO-CLAUDE

video-to-claude

拖入屏幕录制视频，拖动时间轴，给画面添加标注，然后点击 Send——带标注的 WebP 会直接作为视觉输入发送到你的 Claude Code 对话中。

在 Claude Code 中输入 /vtc	Claude 接收到你标注的画面	Claude 读取标注并作出回应

---

工作原理

1. 在 Claude Code 中输入 /vtc

MCP 服务会在开发服务未运行时启动它，创建会话，并在浏览器中打开 http://localhost:3000/capture/{id}。

2. 拖入视频

将 .mp4、.mov、.webm 或任何常见视频文件拖到上传区域。系统会使用 ffmpeg 探测文件，然后激活播放器。

3. 拖动时间轴

使用拖动条或方向键，定位到要截取的时刻。画布覆盖层位于视频画面上方。

4. 为画面添加标注

直接在画布上用红色绘制箭头、方框、徒手标记，并添加文字标签。导出的 WebP 中会包含这些标注——Claude 看到的正是你圈出的内容。

5. 截取并重复

点击 Capture，定格带标注的画面。根据需要重复步骤 3–4，截取任意数量的画面。底部的截取栏会显示缩略图。

6. 发送

点击 Send。MCP await_capture 工具会返回，并将所有带标注的画面作为图像内容块发送到 Claude Code 对话中。

7. Claude 描述它看到的内容

Claude 会读取标注——红色箭头、圈出的元素或文字标签——并直接回应你标记的内容。无需再解释一遍。

---

前置条件

• Node.js 20+（推荐 Node 24）
• Claude Code CLI 已安装（安装指南）
• Windows、macOS 或 Linux
• 无需 Python，也无需将 ffmpeg 添加到 PATH——两者均已打包

---

安装

选项 A — Claude Code 插件（推荐）

/plugin install github:adityaO5/video-to-claude

此操作会一步安装 MCP 服务和 /video-to-claude:vtc 技能。无需单独注册 MCP 或复制命令。

选项 B — npm（仅 MCP，无需克隆）

claude mcp add video-to-claude --scope user -- npx video-to-claude-mcp

或者手动添加到 ~/.claude.json：

{
  "mcpServers": {
    "video-to-claude": {
      "command": "npx",
      "args": ["video-to-claude-mcp"]
    }
  }
}

然后添加 /vtc 命令（见下文）。

选项 C — 克隆并构建

git clone https://github.com/adityaO5/video-to-claude
cd video-to-claude
npm install
npm run mcp:build

然后注册：

claude mcp add video-to-claude --scope user -- node /ABSOLUTE/PATH/TO/video-to-claude/dist/mcp/server.js

将 /ABSOLUTE/PATH/TO/video-to-claude 替换为实际路径。
Windows 示例：C:/Users/you/repos/video-to-claude（JSON 中可以使用正斜杠）。

---

添加 /vtc 斜杠命令（仅适用于选项 B 和 C）

插件安装（选项 A）会自动包含此技能，命令为 /video-to-claude:vtc。

对于选项 B/C，此仓库提供 .claude/commands/vtc.md。Claude Code 仅当你的工作目录位于克隆的仓库内时，才会加载项目级斜杠命令。

如需在任意目录使用 /vtc，请将命令文件复制到用户级命令文件夹：

# macOS / Linux
cp .claude/commands/vtc.md ~/.claude/commands/vtc.md

# Windows (PowerShell)
Copy-Item .claude\commands\vtc.md $HOME\.claude\commands\vtc.md

更改任何配置后，请重启 Claude Code。

---

用法

/vtc

就这么简单。浏览器会打开，你上传视频、拖动播放进度、添加标注并发送，带标注的帧就会出现在对话中。Claude 会读取红色标记并据此操作。

---

MCP 工具

工具	描述
start_capture_session	如有需要，启动开发服务器、创建会话并打开浏览器。返回 sessionId。
await_capture	轮询直到用户点击 Send（默认超时时间为 600 s）。以图像内容块的形式返回带标注的 WebP 图像。

/vtc 斜杠命令会自动依次调用这两个工具。

---

视觉约束

• 格式：WebP（由工具生成）
• 每帧目标大小 ≤ 2 MB（硬性上限为 5 MB）；如果需要，会将质量从 80 逐步降至 50 后重试
• 最大宽度：960 px
• 实际限制：约 20 帧后会自动缩小；软上限约为 100 帧

---

故障排除

开发服务器没有打开？
在仓库目录中运行 npm run dev，然后重试 /vtc。

Claude Code 中看不到 MCP 工具？
运行 claude mcp list 确认已注册。重启 Claude Code。如果使用的是克隆的仓库，请确认 dist/mcp/server.js 存在（如果不存在，请重新运行 npm run mcp:build）。

端口冲突？
MCP 服务会扫描 3000–3005 端口来查找应用。请在空闲端口上运行 npm run dev，或停止其他占用 3000 端口的程序。

大文件上传停滞？
源文件会按 512 KB 分块上传。在速度较慢的磁盘上，超大文件（> 2 GB）可能需要一些时间。

---

技术栈

• Next.js 16 App Router（Node 24）——UI + REST API
• ffmpeg-static ——视频探测 + 单帧提取
• sharp ——SVG 标注合成 + 带质量重试的 WebP 编码
• @modelcontextprotocol/sdk ——MCP stdio 传输

---

许可证

MIT——详见 LICENSE