Публичное обнаружение

mcp-video — это MCP-сервер, библиотека Python и CLI для агентского редактирования видео. Он помогает ИИ-агентам и скриптам автоматизации проверять, обрезать, объединять, добавлять субтитры, изменять размер, перекодировать, анализировать и создавать видео с помощью FFmpeg и рабочих процессов, управляемых кодом.

Поисковые запросы: MCP-сервер для редактирования видео, редактирование видео ИИ-агентами, автоматизация FFmpeg, инструменты видео для Claude, Cursor MCP video, библиотека Python для редактирования видео, агентский медиа-конвейер, CLI для автоматизации видео.

Что такое mcp-video?

Сервер для редактирования видео с открытым исходным кодом, построенный на базе Model Context Protocol (MCP). Он предоставляет ИИ-агентам, разработчикам и создателям видео возможность программно редактировать и создавать видеофайлы.

Два режима:

Редактирование существующего видео с помощью FFmpeg — обрезка, объединение, наложение текста, добавление аудио, применение фильтров, стабилизация, обнаружение сцен, транскрибация и многое другое.
Создание нового видео из кода с помощью Hyperframes (HTML-native, Apache 2.0) — создание композиций, предварительный просмотр в реальном времени, рендеринг в MP4 и последующая обработка.

Три интерфейса:

Интерфейс	Лучше всего подходит для	Пример
MCP-сервер	ИИ-агенты (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-сервер (для ИИ-агентов)

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"])

Агентский контракт:

Вызовы клиента, создающего медиа, возвращают EditResult с .output_path.
Вызовы анализа/обнаружения возвращают типизированные отчеты или словари.
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

87 инструментов MCP в 10 категориях, включая мета-инструмент search_tools для быстрого поиска. Все возвращают структурированный JSON. Подробности см. в полном справочнике инструментов.

Категория	Кол-во	Основное
Core Video	32	обрезка, объединение, текст, аудио, размер, конвертация, фильтры, стабилизация, хромакей, субтитры, водяной знак, пакетная обработка, очистка, предпросмотр шаблона, экспорт
AI-Powered	11	транскрибация (Whisper), обнаружение сцен, разделение дорожек (Demucs), апскейл, цветокоррекция
Hyperframes	8	инициализация, рендер, статика, предпросмотр, композиции, валидация, добавление блока, конвейер
Audio Synthesis	7	генерация волн, пресеты, последовательности, эффекты, пространственное аудио — чистый NumPy
Visual Effects	8	виньетка, хроматическая аберрация, сканлайны, шум, свечение, luma key, маска, маска формы
Transitions	3	глитч, пикселизация, морфинг
Layout & Motion	6	сетка, картинка в картинке, анимированный текст, счетчики, индикаторы прогресса, авто-главы
Analysis	8	обнаружение сцен, миниатюра, предпросмотр, раскадровка, сравнение качества, метаданные, форма волны, контрольная точка выпуска
Image Analysis	3	извлечение цвета, генерация палитры, анализ продукта
Meta	1	`search_tools` — поиск по ключевым словам среди всех инструментов
Resources	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 для всех команд и опций.

Timeline 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 Videos.

Обработка ошибок

Структурированные, полезные ошибки с предложениями по автоматическому исправлению:

{
  "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

Обнаружение агентов

llms.txt — компактная карта проекта для агентов
docs/AI_AGENT_DISCOVERY.md — более подробное позиционирование и фрагменты интеграции

Разработка

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

Сообщество и поддержка

Участие: CONTRIBUTING.md
Безопасность: SECURITY.md (путь для приватных отчетов)
Помощь: SUPPORT.md или GitHub Discussions
Кодекс поведения: CODE_OF_CONDUCT.md
Журнал изменений: CHANGELOG.md
Дорожная карта: ROADMAP.md
Управление: GOVERNANCE.md
Сопровождающие: MAINTAINERS.md

Тестирование

Тесты исключены из пакета PyPI. Для запуска локально:

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

См. docs/TESTING.md для получения информации о категориях тестов и деталях CI.

Лицензия

Apache 2.0 — см. LICENSE.

Построено на FFmpeg, Hyperframes и Model Context Protocol.

См. docs/LEGAL_REVIEW.md для заметок о лицензировании зависимостей.

pastorsimon1798/mcp-video