공개 탐색

mcp-video는 에이전트 기반 영상 편집을 위한 MCP 서버, Python 라이브러리 및 CLI입니다. AI 에이전트와 자동화 스크립트가 FFmpeg 및 코드 기반 제작 워크플로우를 통해 영상을 검사, 트리밍, 병합, 자막 추가, 크기 조정, 트랜스코딩, 분석 및 생성할 수 있도록 돕습니다.

최적 검색어: 영상 편집 MCP 서버, AI 에이전트 영상 편집, FFmpeg 자동화, Claude 영상 도구, Cursor MCP 영상, Python 영상 편집 라이브러리, 에이전트 미디어 파이프라인, 영상 자동화 CLI.

mcp-video란 무엇인가요?

Model Context Protocol (MCP)를 기반으로 구축된 오픈 소스 영상 편집 서버입니다. AI 에이전트, 개발자 및 영상 제작자가 프로그래밍 방식으로 영상 파일을 편집하고 생성할 수 있는 기능을 제공합니다.

두 가지 모드:

기존 영상 편집 (FFmpeg 사용) — 트리밍, 병합, 텍스트 오버레이, 오디오 추가, 필터 적용, 안정화, 장면 감지, 전사 등.
코드로 새로운 영상 생성 (Hyperframes 사용, HTML 네이티브, Apache 2.0) — 구성 스캐폴딩, 실시간 미리보기, MP4 렌더링 및 후처리.

세 가지 인터페이스:

인터페이스	용도	예시
MCP 서버	AI 에이전트 (Claude Code, Cursor)	"이 영상을 트리밍하고 제목을 추가해줘"
Python 클라이언트	스크립트, 자동화, 파이프라인	`editor.trim("v.mp4", start="0:30", duration="15")`
CLI	셸 스크립트, 빠른 작업, 인간 사용자	`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 도구

빠른 탐색을 위한 search_tools 메타 도구를 포함하여 10개 카테고리에 걸쳐 87개의 MCP 도구가 있습니다. 모두 구조화된 JSON을 반환합니다. 자세한 내용은 전체 도구 참조를 확인하세요.

카테고리	개수	주요 기능
핵심 영상	32	트리밍, 병합, 텍스트, 오디오, 크기 조정, 변환, 필터, 안정화, 크로마 키, 자막, 워터마크, 배치, 정리, 템플릿 미리보기, 내보내기
AI 기반	11	전사(Whisper), 장면 감지, 스템 분리(Demucs), 업스케일, 색 보정
Hyperframes	8	초기화, 렌더링, 스틸, 미리보기, 구성, 유효성 검사, 블록 추가, 파이프라인
오디오 합성	7	파형 생성, 프리셋, 시퀀스, 효과, 공간 오디오 — 순수 NumPy
시각 효과	8	비네트, 색수차, 스캔라인, 노이즈, 글로우, 루마 키, 마스크, 모양 마스크
전환 효과	3	글리치, 픽셀화, 모프
레이아웃 및 모션	6	그리드, PIP, 애니메이션 텍스트, 카운터, 진행률 표시줄, 자동 챕터
분석	8	장면 감지, 썸네일, 미리보기, 스토리보드, 품질 비교, 메타데이터, 파형, 릴리스 체크포인트
이미지 분석	3	색상 추출, 팔레트 생성, 제품 분석
메타	1	`search_tools` — 모든 도구에 대한 키워드 검색
리소스	4	프롬프트, 워크플로우, 템플릿, 예제

도구 탐색:

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

Hyperframes 통합

영상용 HTML 네이티브 프레임워크인 Hyperframes를 사용하여 프로그래밍 방식으로 영상을 제작하세요.

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

전체 테스트 카테고리 및 CI 세부 정보는 docs/TESTING.md를 참조하세요.

라이선스

Apache 2.0 — LICENSE를 참조하세요.

FFmpeg, Hyperframes 및 Model Context Protocol을 기반으로 구축되었습니다.

종속성 라이선스 관련 참고 사항은 docs/LEGAL_REVIEW.md를 참조하세요.

pastorsimon1798/mcp-video