Skip to main content
Glama
deenesjakoruzh
KyaniteLabs

pastorsimon1798/mcp-video

by KyaniteLabs
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

公共发现

mcp-video 是一个用于智能体视频编辑的 MCP 服务器、Python 库和 CLI 工具。它帮助 AI 智能体和自动化脚本通过 FFmpeg 和代码驱动的创作工作流来检查、剪辑、合并、添加字幕、调整大小、转码、分析和生成视频。

最佳搜索关键词： 视频编辑 MCP 服务器, AI 智能体视频编辑, FFmpeg 自动化, Claude 视频工具, Cursor MCP 视频, Python 视频编辑库, 智能体媒体流水线, 视频自动化 CLI。

什么是 mcp-video？

这是一个基于 模型上下文协议 (MCP) 构建的开源视频编辑服务器。它赋予 AI 智能体、开发者和视频创作者以编程方式编辑和创建视频文件的能力。

两种模式：

  1. 使用 FFmpeg 编辑现有视频 — 剪辑、合并、叠加文本、添加音频、应用滤镜、稳定画面、场景检测、转录等。

  2. 使用 Hyperframes (HTML 原生, Apache 2.0) 通过代码创建新视频 — 构建组合、实时预览、渲染为 MP4，然后进行后期处理。

三种接口：

接口

适用场景

示例

MCP 服务器

AI 智能体 (Claude Code, Cursor)

“剪辑此视频并添加标题”

Python 客户端

脚本、自动化、流水线

editor.trim("v.mp4", start="0:30", duration="15")

CLI

Shell 脚本、快速操作、人工

mcp-video trim video.mp4 -s 0:30 -d 15

安装

先决条件： 必须安装 FFmpeg。对于 Hyperframes 功能，还需要 Node.js 22+。

# macOS
brew install ffmpeg

# Ubuntu/Debian
sudo apt install ffmpeg

安装：

pip install mcp-video
# or run without installing:
uvx mcp-video

验证您的设置：

mcp-video doctor
mcp-video doctor --json

快速入门

作为 MCP 服务器（面向 AI 智能体）

Claude Code：

claude mcp add mcp-video -- uvx mcp-video

Claude Desktop：

{
  "mcpServers": {
    "mcp-video": {
      "command": "uvx",
      "args": ["mcp-video"]
    }
  }
}

Cursor：

{
  "mcpServers": {
    "mcp-video": {
      "command": "uvx",
      "args": ["mcp-video"]
    }
  }
}

然后只需询问您的智能体：“将此视频从 0:30 剪辑到 1:00，添加一张标题卡，并调整大小以适配 TikTok。”

作为 Python 库

from mcp_video import Client

editor = Client()

info = editor.info("interview.mp4")
clip = editor.trim("interview.mp4", start="00:02:15", duration="00:00:30")
video = editor.merge(clips=["intro.mp4", clip.output_path, "outro.mp4"])
video = editor.add_text(video.output_path, text="EPISODE 42", position="top-center", size=48)
result = editor.resize(video.output_path, aspect_ratio="9:16")

智能体安全的 Python 工作流

对于自主智能体，建议优先使用检查、流水线链式调用和发布检查点：

from mcp_video import Client

client = Client()
print(client.inspect("create_from_images"))  # Real params, aliases, return type

result = client.pipeline(
    [
        {"op": "create_from_images", "images": frames, "fps": 30},
        {"op": "effect_glow", "intensity": 0.2},  # safe capped default
        {"op": "add_audio", "audio_path": "soundtrack.wav", "mix": True},
        {"op": "export", "quality": "high"},
    ],
    output_path="final.mp4",
)

checkpoint = client.release_checkpoint(result.output_path)
print(checkpoint["thumbnail"], checkpoint["storyboard"])

智能体契约：

  • 媒体生产客户端调用返回带有 .output_path 的 EditResult。

  • 分析/发现调用返回类型化的报告或字典。

  • Client.inspect(name) 公开参数、别名、类别和返回类型。

  • 原始的意外关键字错误会被转换为可操作的 MCPVideoError 指导。

  • 在没有 assert_quality() 或 release_checkpoint() 以及人工视觉/音频检查的情况下，请勿发布智能体生成的视频。

作为 CLI 工具

mcp-video info video.mp4
mcp-video trim video.mp4 -s 00:02:15 -d 30
mcp-video convert video.mp4 -f webm -q high
mcp-video template tiktok video.mp4 --caption "Check this out!"

MCP 工具

涵盖 10 个类别的 87 个 MCP 工具，包括用于快速发现的 search_tools 元工具。所有工具均返回结构化的 JSON。详情请参阅 完整工具参考。

类别

数量

亮点

核心视频

32

剪辑、合并、文本、音频、调整大小、转换、滤镜、稳定、色度键、字幕、水印、批处理、清理、模板预览、导出

AI 驱动

11

转录 (Whisper)、场景检测、音轨分离 (Demucs)、超分辨率、调色

Hyperframes

8

初始化、渲染、静态图、预览、组合、验证、添加块、流水线

音频合成

7

生成波形、预设、序列、效果、空间音频 — 纯 NumPy

视觉特效

8

暗角、色差、扫描线、噪点、发光、亮度键、遮罩、形状遮罩

转场

3

故障、像素化、变形

布局与运动

6

网格、画中画、动画文本、计数器、进度条、自动章节

分析

8

场景检测、缩略图、预览、故事板、质量对比、元数据、波形、发布检查点

图像分析

3

颜色提取、调色板生成、产品分析

元工具

1

search_tools — 跨所有工具的关键字搜索

资源

4

提示词、工作流、模板、示例

工具发现：

from mcp_video import Client
editor = Client()
results = editor.search_tools("subtitle")  # Find subtitle-related tools

Hyperframes 集成

使用 Hyperframes（一种用于视频的 HTML 原生框架）以编程方式创建视频。

1. Init project       -> hyperframes_init
2. Add blocks         -> hyperframes_add_block
3. Preview live       -> hyperframes_preview
4. Render             -> hyperframes_render
5. Post-process       -> hyperframes_to_mcpvideo

请参阅 Hyperframes 文档 和 Python 客户端参考。

Python 客户端

from mcp_video import Client
editor = Client()

请参阅 完整 Python 客户端参考 以获取所有方法和返回类型。

CLI 参考

mcp-video [command] [options]

请参阅 完整 CLI 参考 以获取所有命令和选项。

时间轴 DSL

对于复杂的多轨道编辑，请在单个 JSON 对象中描述所有内容：

editor.edit({
    "width": 1080,
    "height": 1920,
    "tracks": [
        {
            "type": "video",
            "clips": [
                {"source": "intro.mp4", "start": 0, "duration": 5},
                {"source": "main.mp4", "start": 5, "trim_start": 10, "duration": 30},
                {"source": "outro.mp4", "start": 35, "duration": 10},
            ],
            "transitions": [
                {"after_clip": 0, "type": "fade", "duration": 1.0},
            ],
        },
        {
            "type": "audio",
            "clips": [
                {"source": "music.mp3", "start": 0, "volume": 0.7, "fade_in": 2},
            ],
        },
    ],
    "export": {"format": "mp4", "quality": "high"},
})

模板

针对常见社交媒体格式的预构建模板：

from mcp_video.templates import tiktok_template, youtube_shorts_template

timeline = tiktok_template(video_path="clip.mp4", caption="Check this out!", music_path="bgm.mp3")
result = editor.edit(timeline)

支持：TikTok, YouTube Shorts, Instagram Reels/Posts, YouTube 视频。

错误处理

结构化、可操作的错误，并提供自动修复建议：

{
  "success": false,
  "error": {
    "type": "encoding_error",
    "code": "unsupported_codec",
    "message": "Codec error: vp9 — Auto-convert input from vp9 to H.264/AAC before editing",
    "suggested_action": {
      "auto_fix": true,
      "description": "Auto-convert input from vp9 to H.264/AAC before editing"
    }
  }
}

工作流

针对常见制作的 ICM 风格分阶段流水线 — 包含 CONTEXT.md 阶段契约、references/ 工厂配置和可运行的 workflow.py 脚本。

cd workflows/01-social-media-clip
python workflow.py /path/to/video.mp4

工作流

阶段

描述

01-social-media-clip

5

横屏 → TikTok / Short / Reel

02-podcast-clip

6

带章节 + 硬编码字幕的精彩片段

03-explainer-video

7

从零开始制作品牌解说视频

04-hyperframes-video

5

使用 Hyperframes 从零创建，然后进行后期处理

请参阅 workflows/CONTEXT.md 获取路由表。

架构

mcp_video/
  client/                # Python Client API (mixins per domain)
  client/meta.py         # Client discovery mixin (search_tools)
  server.py              # MCP server (87 tools + 4 resources)
  server_tools_*.py      # Tool registration by category
  engine.py              # Core FFmpeg engine
  engine_*.py            # Specialized engines (thumbnail, edit, probe, etc.)
  models.py              # Pydantic models
  errors.py              # Error hierarchy + FFmpeg stderr parser
  ffmpeg_helpers.py      # Shared FFmpeg utilities
  audio_engine.py        # Procedural audio synthesis
  effects_engine.py      # Visual effects + motion graphics
  transitions_engine.py  # Clip transitions
  ai_engine.py           # AI features (Whisper, Demucs, Real-ESRGAN)
  hyperframes_engine.py  # Hyperframes CLI wrapper
  image_engine.py        # Image color analysis
  quality_guardrails.py  # Automated quality checks
workflows/               # ICM staged pipelines
  CONTEXT.md             # Layer 1 routing table
  01-social-media-clip/  # Stage contract + runnable script
  02-podcast-clip/       # Stage contract + runnable script
  03-explainer-video/    # Stage contract + runnable script

支持的格式

视频

音频 (提取)

字幕

MP4, WebM, MOV, GIF

MP3, AAC, WAV, OGG, FLAC

SRT, WebVTT

智能体发现

开发

git clone https://github.com/KyaniteLabs/mcp-video.git
cd mcp-video
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

社区与支持

测试

测试已从 PyPI 包中排除。要在本地运行：

pip install -e ".[dev]"
pytest tests/ -v -m "not slow and not hyperframes"

请参阅 docs/TESTING.md 获取完整的测试类别和 CI 详情。

许可证

Apache 2.0 — 请参阅 LICENSE。

基于 FFmpeg, Hyperframes 和 模型上下文协议 构建。

请参阅 docs/LEGAL_REVIEW.md 获取依赖项许可说明。

Install Server
A
license - permissive license
A
quality
A
maintenance

How are these scores calculated?

Maintenance

–Maintainers
<1hResponse time
1dRelease cycle
28Releases (12mo)
Issues opened vs closed

Resources

Tools

View all tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/KyaniteLabs/mcp-video'

If you have feedback or need assistance with the MCP directory API, please join our Discord server