Video Decomposer MCP

视频分解器

用于视频分解的MCP服务器：下载视频、转录音频、识别说话者和提取关键帧。作为HTTP MCP服务器运行，并包含一个用于本地使用的CLI。

• 特性
• 先决条件
• 快速开始
• MCP工具
• 命令行用法
• Whisper型号
• 建筑

- - 从预构建的映像运行 - 与mcp远程连接 - Claude桌面配置

• 本地开发
• 配置

- 环境变量 - 卷装载

• 许可证

特性

• 视频下载 通过yt-dlp；支持YouTube、Facebook、Instagram和 1000+其他网站
• 音频转录 随着 WhisperX （更快的耳语后端），在GPU可用时具有CUDA加速功能
• 演讲者日记 通过 pyannote.audio --识别每个分段中的发言者（通过以下方式选择加入 diarize_speakers，要求 HF_TOKEN).日记化对于多说话者视频很有用，但偶尔可能会错误地分配片段或将单个说话者拆分到多个标签上；如果准确性至关重要，请检查输出。
• 帧提取 在任意时间戳，以可配置分辨率和质量的本地MCP图像内容返回
• 综合分析 在一次通话中下载和转录的工作流程，可选日记
• Docker镜像 通过GPU直通、硬件加速的FFmpeg（NVDEC/NVENC）和持久缓存
• 自动清理 4小时后下载的视频

先决条件

对于Docker（推荐）：

• Docker和Docker Compose
• 安装了驱动程序的NVIDIA GPU
• NVIDIA容器工具包

对于当地发展：

• Python 3.12
• 紫外线 包管理器
• NVIDIA GPU+CUDA驱动程序（用于GPU加速转录）
• FFmpeg
• A. 拥抱脸访问令牌 (HF_TOKEN)在可接受的条件下 发音/扬声器发音-3.1 （演讲者日记需要）

快速开始

# Set up environment
cp .env.example .env
# edit .env to add HF_TOKEN for speaker diarization model

# Build the Docker images locally (CUDA variant by default)
./build-local.sh

# Start the MCP server
docker compose up

# In another terminal, test with mcp-remote
npx -y mcp-remote http://localhost:8000/sse

或者直接使用CLI：

uv sync
uv run cli analyze https://www.youtube.com/watch?v=dQw4w9WgXcQ

MCP工具

服务器通过MCP协议公开了四个工具：

analyze_video 是推荐的切入点；它下载视频并返回带有时间戳片段的转录本。使用返回的 video_id 以及分段时间戳 extract_frame 查看特定时刻屏幕上的内容。

命令行用法

CLI提供与MCP服务器相同的本地使用功能：

# Download a video and get its ID
uv run cli download ""

# Transcribe a downloaded video
uv run cli transcribe abc123def456

# Extract a frame at 30.5 seconds
uv run cli extract-frame abc123def456 30.5 --output-dir ./frames

# Download and transcribe in one step
uv run cli analyze ""

Whisper型号

这 whisper_model 参数控制用于转录的特定Whisper模型：

Whisper支持多种语言，但英语的准确性最高；对于非英语音频， large 可以产生更好的结果。

建筑

A. VideoStore 通过短十六进制ID管理磁盘上下载的视频。视频在4小时后过期，背景清理循环每10分钟运行一次。转录、对齐和说话者日记结果作为JSON文件缓存在每个视频的目录中。使用相同参数的重复调用跳过了昂贵的GPU计算。长期运行的工具通过MCP进度通知报告进度，以防止客户端超时。

graph TD
    Client["Client (Claude, LLM tool, CLI)"]
    MCP["MCP Server
server.py
SSE on :8000"]
    DL["download
yt-dlp"]
    TR["transcribe
WhisperX + pyannote"]
    FR["extract_frame
PyAV + OpenCV"]
    AN["analyze
download + transcribe"]
    VS["VideoStore
temp dir, 4h TTL"]

    Client -->|MCP protocol| MCP
    MCP --> DL
    MCP --> TR
    MCP --> FR
    MCP --> AN
    AN --> DL
    AN --> TR
    DL --> VS
    TR --> VS
    FR --> VS

Docker和mcp远程

使用Docker构建和运行

在本地构建基础映像（FFmpeg+PyAV）和应用程序映像：

# CUDA variant (default)
./build-local.sh

# Or CPU-only variant
./build-local.sh cpu

基础图像(Dockerfile.base)包含用NVDEC/NVENC编译的FFmpeg和从源代码构建的PyAV。它很少发生变化，只有在FFmpeg或PyAV版本发生碰撞时才需要重建。应用程序图像(Dockerfile)将Python依赖关系和源代码放在最上面。

然后启动服务器：

docker compose up

服务器监听端口8000。下载的视频存储在 ./video_store，在容器重新启动时持续存在。

\[！注意\] GPU兼容性： 默认配置使用CUDA 12.8 PyTorch控制盘，支持Maxwell（sm_50）到Blackwell（sm_120）的NVIDIA GPU。如果您有不受支持的较旧或较新的GPU架构，请更新 pytorch-cu128 索引URL pyproject.toml 到相应版本 PyTorch的安装页面 并在中更新CUDA基础图像 Dockerfile.base 为了匹配。

从预构建的映像运行

预构建图像以两种形式发布到GHCR：

使用NVIDIA GPU：

docker run --gpus all -p 8000:8000 \
  -v ./video_store:/app/video_store \
  ghcr.io/icooper/video-decomposer-mcp:-cu128

仅限CPU：

docker run -p 8000:8000 \
  -v ./video_store:/app/video_store \
  ghcr.io/icooper/video-decomposer-mcp:-cpu

\[！注意\] 替换 ` 具有特定的释放（例如。， 1.2.0 或 1.2).不使用 latest`。参见 视频分解器mcp包 对于可用版本。

与mcp远程连接

mcp遥控器 将HTTP/SSE MCP服务器桥接到大多数LLM工具所期望的stdio传输。这允许您将视频解压缩器与任何兼容MCP的客户端一起使用：

npx -y mcp-remote http://YOUR_HOST:8000/sse

替换 YOUR_HOST 使用运行服务器的机器的主机名或IP。

Claude桌面配置

将此添加到您的 claude_desktop_config.json 使视频分解器工具在Claude Desktop中可用：

{
  "mcpServers": {
    "video-decomposer": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://YOUR_HOST:8000/sse"]
    }
  }
}

类似的方法应该适用于支持stdio服务器的任何其他MCP客户端。

本地开发

# Install dependencies
uv sync

# Run the test suite (enforces 100% code coverage)
uv run pytest

# Start the MCP server locally
uv run server

Python 3.12是必需的。PyTorch是从中配置的CUDA 12.8索引安装的 pyproject.toml.

配置

环境变量

卷装载

容器内的这些路径可以分配给Docker卷，以在容器重启时持久化数据。

\[！提示\] - 分配 /app/hf_cache 添加到卷中是有益的，因为它消除了每次容器启动时重新下载用于转录和说话者日记的模型的需要。 - 默认 docker-compose.yml 暴露所有GPU(device_ids: ["all"]).要限制特定GPU，请编辑 device_ids 列表（例如。， ["0"] 或 ["0", "1"]).

许可证

看 许可证.md.