内容
<div align="center">
# 🎬 视频阅读器 MCP
<p align="center">
<img src="https://mark.sylphx.com/api/v1/banner?type=mesh&theme=tokyonight&text=video+reader+mcp&desc=Evidence-first+video+reading+for+AI+agents+%E2%80%94+ffprobe%2C+subtitles%2C+scenes%2C+transcr&height=200&animation=rise&credit=0" alt="video-reader-mcp — Sylphx Mark banner" width="100%" />
</p>
### 您的智能代理已经观看了视频。**它是否读取了时间线？**
为 AI 代理提供基于证据的视频阅读能力。一次调用可以将任何本地视频转换为**时间线文档**，包括 ffprobe 流、章节、嵌入式字幕、场景边界和警告，您可以引用这些信息而无需逐帧视觉 LLM 调用。
[](https://www.npmjs.com/package/@sylphx/video-reader-mcp)
[](https://opensource.org/licenses/MIT)
[](https://github.com/SylphxAI/video-reader-mcp/actions/workflows/ci.yml)
[](https://www.typescriptlang.org/)
**本地优先** · **一次智能的 `read_video` 调用** · **时间线证据 + 来源** · **20 个测试**
SOTA 家族路线图：[docs/roadmap/sota-family-roadmap.md](docs/roadmap/sota-family-roadmap.md)。
[⭐ 给这个仓库点赞](https://github.com/SylphxAI/video-reader-mcp) 如果智能代理应该使用证据阅读视频时间线，而不是采样帧字幕。
· [快速开始](#快速开始) · [查看其工作原理](#查看其工作原理) · [为什么不使用逐帧视觉？](#为什么不使用逐帧视觉)
Sylphx Reader 组合的一部分 — 协调和投资组合 ADR 位于
[smart-reader-mcp](https://github.com/SylphxAI/smart-reader-mcp)。
</div>
---
## 问题
视频不仅仅是一堆帧。它们是编解码器、章节、嵌入式字幕、场景剪辑、可变帧率和毫秒级时间线。
大多数智能代理堆栈会采样帧并询问视觉 LLM 看到了什么。字幕被跳过。场景边界消失。时长和流元数据永远不会到达上下文。引用变成“大约在第 2 分钟，我想”。然后智能代理就会产生幻觉 — 自信地。
**视频阅读器 MCP 旨在为您的智能代理在需要可引用的时间线时使用，而不是幻灯片摘要。**
## 为什么不使用逐帧视觉？
| 典型的视觉路径 | 视频阅读器 MCP |
| --- | --- |
| 将 N 帧采样到视觉模型中 | 一次调用获取 ffprobe 格式 + 流元数据 |
| 意译的“发生了什么” | 带有 `start_ms`、`end_ms` 和来源的嵌入式字幕提示 |
| 从字幕中猜测场景变化 | 可选的 ffmpeg 场景过滤器，带有时间戳证据 |
| 丢失的音频 / VFR 被默默忽略 | 对丢失的 ffmpeg/ffprobe、VFR、丢失的音频、跳过的 ASR 的警告 |
| 默认使用云 API | **本地优先** — ffprobe + ffmpeg 在您的机器上 |
| 交付并祈祷 | **20** 个解析器、固定装置、医生、发布门和集成测试 |
## 查看其工作原理
**安装一次。调用一次。**
```bash
claude mcp add video-reader -- npx @sylphx/video-reader-mcp
```
```json
{
"sources": [{ "path": "/absolute/path/to/demo.mp4" }],
"include_subtitles": true,
"include_scenes": true
}
```
`read_video` 为每个源构建一个时间线文档 — 无需逐帧视觉 LLM 调用：
```json
{
"source": "/absolute/path/to/demo.mp4",
"success": true,
"data": {
"provenance": {
"source": "/absolute/path/to/demo.mp4",
"tool": "read_video",
"version": "0.1.0",
"extracted_at": "2026-07-09T12:00:00.000Z"
},
"format": {
"format_name": "mov,mp4,m4a,3gp,3g2,mj2",
"duration_ms": 125500
},
"streams": [
{ "index": 0, "codec_type": "video", "width": 1920, "height": 1080 },
{ "index": 1, "codec_type": "audio", "channels": 2, "sample_rate": 48000 }
],
"chapters": [
{ "id": 0, "start_ms": 0, "end_ms": 60250, "title": "Intro" }
],
"subtitles": [
{
"index": 0,
"start_ms": 1200,
"end_ms": 3400,
"text": "Welcome to the demo.",
"provenance": { "method": "ffmpeg_extract", "format": "srt" }
}
],
"scenes": [
{
"index": 0,
"time_ms": 45200,
"provenance": { "method": "ffmpeg_scene_filter", "threshold": 0.4 }
}
],
"warnings": []
}
}
```
缩略的形状 — 可选的本地 ASR 转录钩子在没有连接适配器时跳过。
## 先决条件
- Node.js `>=22.13`
- **ffprobe** （必需）和 **ffmpeg** （推荐用于字幕和场景）位于 `PATH`
## MCP 工具表面
| 工具 | 用例 |
| --- | --- |
| `read_video` | 读取一个或多个本地视频并返回 ffprobe 元数据、章节、字幕、场景和时间线警告。 |
支持的格式：MP4、M4V、MKV、MOV、WebM 和其他 ffprobe 可以检查的格式。
## 快速开始
### Claude 代码
```bash
claude mcp add video-reader -- npx @sylphx/video-reader-mcp
```
### Claude 桌面版
将以下内容添加到 `claude_desktop_config.json`：
```json
{
"mcpServers": {
"video-reader": {
"command": "npx",
"args": ["@sylphx/video-reader-mcp"]
}
}
}
```
### 任意 MCP 客户端
```bash
npx @sylphx/video-reader-mcp
```
### HTTP 传输（可选）
```bash
MCP_TRANSPORT=http MCP_HTTP_PORT=8080 npx @sylphx/video-reader-mcp
```
## 安全模型
- **本地优先** — `read_video` 检查本地文件；默认情况下不获取远程 URL。
- **ffprobe/ffmpeg 边界** — 探测和帧工具使用 PATH 上配置的二进制文件；缺少的工具会返回明确的错误。
- **固定装置** — CI 验证解析器和安全固定装置；损坏的输入会以结构化诊断关闭。
- **证据信封** — 时间戳、帧索引和提取路由被保留，以便智能代理可以验证声明。
## 发布证明
声明由 CI `benchmark:release-gate`、固定装置检查和发布的路径矩阵（Rust 默认主要工具）支持。
```bash
bun run benchmark:release-gate
```
制品：`benchmark-artifacts/video_reader_release_gate.json` — 必须在发布前报告 `status: passed`。
## 开发
```bash
git clone https://github.com/SylphxAI/video-reader-mcp.git
cd video-reader-mcp
bun install
bun run build
bun test
bun run doctor
bun run benchmark:release-gate
```
有用检查：
```bash
bun run check
bun run typecheck
bun run benchmark:release-gate
```
示例 `read_video` 请求位于 [`examples/`](examples/) 中。CI 运行解析器、固定装置、医生和发布门检查；集成测试在可用时运行 ffmpeg。
## 支持
- [问题](https://github.com/SylphxAI/video-reader-mcp/issues)
- [npm 包](https://www.npmjs.com/package/@sylphx/video-reader-mcp)
- 投资组合协调：[smart-reader-mcp](https://github.com/SylphxAI/smart-reader-mcp)
## 帮助它惠及更多开发者
如果逐帧视觉猜测浪费了您的上下文、引用或对智能代理输出的信任，您就是这个项目的使用者。
**[⭐ 给这个仓库点赞](https://github.com/SylphxAI/video-reader-mcp)** — 这是帮助更多智能代理开发者找到基于证据的视频阅读的最快方式。在您的 MCP 客户端设置、团队 wiki 或智能代理堆栈 README 中分享它。
### 发现（进行中）
| 频道 | 状态 |
| --- | --- |
| [Glama MCP 目录](https://glama.ai/mcp/servers/SylphxAI/video-reader-mcp) | 已列出 — [声明服务器](https://glama.ai/mcp/servers/SylphxAI/video-reader-mcp/admin) 以实现完全可发现性 |
| [官方 MCP 注册表](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.SylphxAI/video-reader-mcp) | 已列出 — `io.github.SylphxAI/video-reader-mcp` @ v0.1.0 |
| [TensorBlock MCP 索引 PR #1113](https://github.com/TensorBlock/awesome-mcp-servers/pull/1113) | 已打开 — 多媒体/文档处理列表 |
| [MCP 服务器社区问题 #4500](https://github.com/modelcontextprotocol/servers/issues/4500) | 已打开 — 社区服务器亮点 |
| [mcp.so 列表问题 #3068](https://github.com/chatmcp/mcpso/issues/3068) | 已打开 — 目录提交请求 |
| [mcpservers.org 提交](https://mcpservers.org/submit) | 尚未列出 — 免费网络表单提交 |
了解另一个 MCP 目录？[打开一个问题](https://github.com/SylphxAI/video-reader-mcp/issues/new) 并附上链接。
## 许可证
MIT © [SylphxAI](https://github.com/SylphxAI)
