AI导哈

视频分解服务

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

  • by icooper
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 icooper/video-decomposer-mcp

使用说明

视频分解器

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

特性

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

先决条件

对于Docker（推荐）：

对于当地发展：

快速开始

# 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协议公开了四个工具：

工具 参数 返回 描述
download_video url video_id （string） 下载视频。返回用于其他工具的ID。
transcribe_video video_id, whisper_model?, diarize_speakers?, align_language? {text, segments} 转录音频。可选择通过以下方式识别说话者 diarize_speakers.
extract_frame video_id, timestamp, max_dimension?, quality? MCP图像内容（JPEG） 将单个帧提取为JPEG图像（默认情况下，最长边最大为768px）。
analyze_video url, whisper_model?, diarize_speakers?, align_language? {video_id, transcript} 下载+转录在一个电话。视频分析的最佳起点。

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

命令行用法

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

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

# 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 "<url>"

Whisper型号

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

型号 参数 相对速度 所需VRAM 注意事项
turbo 809M ~8x ~6GB 默认值。最佳速度/质量折衷。
base 74M ~16x ~1GB 速度快，精度低。
small 244M ~6x ~2 GB 中等质量。
medium 769M ~2x ~5GB 质量好，速度慢。
large 1550M 1x ~10 GB 质量最好，速度最慢。

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

建筑

服务器由以下组件构建 FastMCP 并委托给包装工具模块 yt-dlp, WhisperX （更快的耳语+pyannote音频）， PyAV，以及 OpenCV所有阻塞操作（下载、转录、日记化、帧提取）均通过以下方式运行 asyncio.run_in_executor() 以保持异步事件循环的响应。

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

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

    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：

标签后缀 描述 示例
-cu128 CUDA 12.8，支持GPU ghcr.io/icooper/video-decomposer-mcp:<version>-cu128
-cpu 仅CPU（不需要GPU） ghcr.io/icooper/video-decomposer-mcp:<version>-cpu

使用NVIDIA GPU：

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

仅限CPU：

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

[！注意] 替换 <version> 具有特定的释放（例如。， 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.

配置

环境变量

变量 默认值 描述
HF_TOKEN （无） 拥抱脸访问令牌pyannote.audio扬声器日记
LOG_LEVEL INFO 记录冗长(DEBUG, INFO, WARNING, ERROR, CRITICAL)
MCP_HOST 127.0.0.1 MCP服务器绑定到的主机地址
MCP_PORT 8000 MCP服务器监听的端口
PRELOAD_ALIGN_LANGUAGE en 启动时预加载的对齐模型语言
VIDEO_STORE_TTL_SECONDS 14400 视频过期时间（秒）（默认为4小时）
VIDEO_STORE_CLEANUP_INTERVAL_SECONDS 600 清理循环间隔（秒）（默认为10分钟）
WHISPER_MODEL turbo 要预加载和使用的默认Whisper型号

卷装载

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

容器路径 描述
/app/hf_cache HuggingFace缓存，用于转录和说话者日记模型。装载以避免在容器重新启动时重新下载模型。
/app/nltk_data NLTK标记器数据。装载以避免在容器重新启动时重新下载。
/app/video_store 下载的视频和缓存的转录结果。装载以在容器重新启动时保持不变。

[！提示]

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

许可证

看 许可证.md.

相关 MCP