Kinocut
- 추천0
- GitHub 별272
- 영상라이선스Apache-2.0
에이전트가 영상을 편집하고 사람은 컷을 승인하는 로컬 영상 편집 MCP 서버·파이썬 클라이언트·CLI. FFmpeg 기반, Apache-2.0
Kinocut(으)로 무엇을 할 수 있나요?
- 안전한 기본값 — 덮어쓰기는 명시해야 하고, 편집 전에 범위·호환성을 먼저 검증합니다
- 자연어 편집 — video_direct가 말을 계획으로 바꾸고, 승인 후 video_direct_apply로 실행
- 세로 쇼츠 한 번에 — video_shorts로 고른 구간을 9:16 쇼츠로 만듭니다
- 품질 검사 — 검은 화면·무음·음량 문제를 컷을 보기 전에 잡습니다
- Video Receipt — 요청·실행·변경 내용을 기록으로 남깁니다
- 작은 기본 목록 — 기본 18개 도구, 나머지는 list_operations로 한 번 더 호출
- 로컬 · 무료 — 계정·업로드·크레딧 없이 내 컴퓨터에서 실행
- 세 가지 사용 방식 — MCP 서버, 파이썬 Client, kino CLI가 같은 엔진을 씁니다
설치 방법은 설치 탭에 정리했어요.
설명
Kinocut
영상은 에이전트가 편집하고, 컷은 당신이 승인합니다.
로컬에서 돌아가는 가드레일 영상 편집 MCP 서버, 파이썬 클라이언트, kino CLI입니다.
무료, Apache-2.0. 예전 이름은 mcp-video입니다.
Hermes에서: hermes plugins install kinocut을 실행한 뒤 저장소의
Hermes 플러그인 안내를 보세요. 다른 에이전트는 아래 설치 방법을 보세요.
에이전트에게 *"이 인터뷰에서 가장 좋은 45초를 잘라 자막 달린 세로 쇼츠로 만들어 줘"*라고 말했다고 해 봅시다. 도움이 없으면 에이전트는 FFmpeg 옵션을 짐작하고, 원본을 덮어쓰고, 자기도 확인해 보지 않은 파일을 내놓습니다.
Kinocut은 그 대신 타입이 정해진 도구를 에이전트에게 줍니다. 모든 편집은 FFmpeg가 돌기 전에 검사하고, 덮어쓰기를 허용하지 않는 한 새 파일에 쓰며, 에이전트가 살펴볼 수 있는 구조화된 결과를 돌려줍니다. 품질 게이트가 검은 화면, 무음, 잘못된 음량을 컷을 보기 전에 잡아 주고, Video Receipt가 무엇을 요청했고 무엇이 실행됐고 무엇이 바뀌었는지 기록합니다.
모든 것이 내 컴퓨터에서 돌아갑니다. 계정도, 업로드도, 크레딧도 없습니다.
설치
Kinocut은 PATH에 FFmpeg가 있어야 합니다(brew install ffmpeg, sudo apt install ffmpeg, winget install ffmpeg).
Claude Code에 추가:
claude mcp add kinocut -- uvx --from kinocut==2.0.1 kino --mcp
JSON 설정을 읽는 MCP 클라이언트(Claude Desktop, Cursor, Windsurf, Zed)는 이렇게 추가합니다.
{
"mcpServers": {
"kinocut": {
"command": "uvx",
"args": ["--from", "kinocut==2.0.1", "kino", "--mcp"]
}
}
}
패키지를 설치하고 내 컴퓨터를 점검할 수도 있습니다.
pip install kinocut==2.0.1
kino doctor
kino doctor는 어떤 기능이 준비됐고, 빠진 기능에는 무엇이 필요한지 알려 줍니다. 선택 기능은 extras로 설치하며, 전체 목록은 설치 표에 있습니다.
Claude Desktop 확장으로 설치하려면 python3 scripts/build-mcpb.py로 mcpb/에서 로컬 .mcpb를 만듭니다. 서명되지 않았고 user-configured-local-access로 표시됩니다. 내 파이썬 환경을 실행하고, 여전히 Node와 FFmpeg가 필요하며, 샌드박스가 아닙니다. docs/MCPB.md를 보세요.
에이전트에게 보이는 것
에이전트는 읽는 도구 설명마다, 매 턴 비용을 냅니다. Kinocut은 기본 목록을 작게 유지하고 나머지는 한 번만 더 부르면 닿게 해 둡니다.
| 모드 | 설정 | 보이는 도구 | 구성 |
|---|---|---|---|
| 기본 | 설정 없음 | 18 | 자주 쓰는 도구 8개, 작업 묶음 8개, list_operations, describe_operation |
| 프로필 | KINOCUT_TOOLS=profile:editor (프로필 19종) | 프로필마다 다름 | 한 작업에 필요한 도구를 이름으로, 그리고 작업 묶음 |
| 전부 | KINOCUT_TOOLS=all | 206 | 모든 도구를 각자 이름으로 |
자주 쓰는 도구는 video_info, video_trim, video_merge, video_add_text, video_add_audio, video_extract_frame, video_shorts, video_doctor입니다.
작업 묶음 여덟 개(video_edit_ops, video_effects_ops, audio_ops, video_ai_ops, image_ops, video_qc_ops, video_plan_ops, platform_ops)가 카탈로그의 나머지 작업에 모두 닿습니다. 에이전트는 list_operations로 한 묶음이 할 수 있는 일을 보고, describe_operation으로 작업 하나의 전체 스키마를 가져옵니다. 묶음을 통한 호출은 이름이 붙은 도구와 같은 코드를 실행하므로 결과가 같습니다. MCP 작업 묶음을 보세요.
기본 18개 도구 목록은 JSON으로 약 22 KB이고, 전체 카탈로그는 약 178 KB입니다.
지금 쓰는 곳에서 컷 검토하기
- Hermes Desktop 채팅.
video_review_card가 컨택트 시트, 길이, 해상도, 코덱과 버튼 세 개(승인 후 내보내기, 더 파 보기, 다른 구간 시도)가 있는 HTML 카드를 씁니다. 선택형 데스크톱 플러그인은 상태 표시줄에 실시간 렌더 진행률을, 「Kinocut renders」 창에 렌더 목록을 보여 줍니다. Hermes 플러그인을 보세요. - 짝지은 Hermes Gadget TV. 플러그인 스킬이 컷을 TV에 띄우고, 리모컨의 승인·거절을 「승인 후 내보내기」·「다른 구간 시도」에 연결할 수 있습니다. TV가 가져갈 수 있는 URL이 필요하며, Kinocut이 그 URL을 제공하지는 않습니다.
- 그 밖의 곳.
kino release-checkpoint clip.mp4가 클립 옆에 썸네일, 스토리보드, 통과·실패 품질 보고서를 씁니다.
하고 싶은 말을 그대로
에이전트에게 평소 말로 부탁하면 됩니다. 에이전트는 그 말을 그대로 video_direct에 넘기고, 가정한 내용을 한 문장으로 되읽어 주며, 계획에 질문이 하나 있으면 그것을 묻습니다. 당신이 승인하면 video_direct_apply(plan=plan, confirm=true)를 부릅니다. 기본 화면에서는 두 가지 모두 video_plan_ops의 작업입니다. 계획 단계는 원본을 살펴볼 뿐 렌더링하거나 파일을 저장하지 않습니다. Hermes는 이미 음성 메모를 글로 바꿔 줍니다. 선택 항목인 audio_path 음성 메모는 글 지시가 없을 때만, 이미 있는 로컬 전사 경로로 처리합니다.
- "좀 줄여 주고 빈 소리 구간을 잘라 줘" → 소리 여유를 짧게 두고 무음 제거.
- "틱톡용 30초 세로 영상에 자막 넣어 줘" → 처음 30초까지만 남기고, 1080×1920으로 크기를 바꾸고, 최종 타이밍으로 받아쓴 뒤 자막을 입힘.
- "소리가 너무 작아, 처음 5초는 빼 줘" → 앞부분을 자르고 -14 LUFS로 정규화.
kino direct "make it punchier and give me a thumbnail" -i in.mp4 -o out.mp4로 JSON을 검토할 수 있습니다. 실제로 실행하려면 --apply를 붙입니다. 질문에 답하지 않으면 검토 상태로 남습니다. MCP로 넘기는 경로는 절대 경로여야 합니다. 중간 클립, 자막 사이드카 파일, 썸네일은 출력 파일 옆에 정해진 이름으로 만들어집니다. 돌려받은 계획 JSON은 에이전트 대화 안에 두세요. KinoCut은 그것을 저장하지 않습니다.
계획은 기본값과 알아듣지 못한 표현을 공개합니다. 길이를 줄일 때는 정리한 뒤 앞부분을 남기고, 가장 좋은 순간을 고르지는 않습니다. 화면 비율을 바꿀 때는 가운데 크롭을 쓰므로 눈으로 확인해야 합니다. 음소거는 모든 소리를 끄며, 음악만 따로 지우는 일은 모델 추론이 필요해 「인식하지 못함」으로 남깁니다. 자막 생성과 음성 메모 전사에는 선택 사항인 로컬 전사 의존성이 필요합니다. 말소리가 없으면 자막 단계는 건너뛰고, 영수증에는 실제 최종 영상이 기록됩니다.
할 수 있는 일
| 작업 | 시작할 곳 |
|---|---|
| 자르기, 합치기, 자막, 크기 변경, 변환, 오버레이, 크롭, 속도 | 자주 쓰는 도구와 video_edit_ops |
| 고른 구간으로 세로 쇼츠 한 번에 | video_shorts |
| 팟캐스트·스트림을 Shorts·Reels·TikTok 패키지로 | 튜토리얼, stream-to-shorts |
| 음량·품질·배포 게이트 | video_qc_ops, 품질 근거 |
| JSON 명세 하나로 여러 단계 작업(재개 가능) | 워크플로 엔진 |
| 이야기를 바꾸지 않고 손상된 클립 진단·복구 | 영상 구조 |
| AI 생성 영상 검토와 살리기 | AI 영상 검토 |
| 이어 붙인 360 MP4 하나로 2캠 편집 | 360 조립 |
| 정지 사진이나 턴테이블 영상에서 제품 오려 내기 | 제품 매트 |
| 대표 이미지에 맞춰 정지 사진 색 맞추기·보정 | Still plates |
| 음성 오디오 믹스·더킹·마스터링·점검 | 오디오 믹싱, 사운드 믹스 |
| 코드로 만드는 모션 그래픽 | Hyperframes · Revideo 도구, 도구 참조 |
| 최종 내보내기에 서명된 출처 정보 | C2PA |
세 가지 인터페이스 뒤에는 같은 엔진이 있습니다.
from kinocut import Client
kino = Client()
clip = kino.trim("interview.mp4", start="00:02:15", duration=45)
kino.ai_transcribe(clip.output_path, output_srt="captions.srt")
captioned = kino.subtitles(clip.output_path, subtitle_file="captions.srt")
vertical = kino.resize(captioned.output_path, aspect_ratio="9:16")
kino.release_checkpoint(vertical.output_path)
kino info interview.mp4
kino trim interview.mp4 -s 00:02:15 -d 45
kino release-checkpoint clip.mp4 --profile ui-capture-dark
참고: MCP 도구 · 파이썬 클라이언트 · CLI · Video Receipts · 에이전트 탐색 · 모든 문서 · llms.txt
기본값이 안전합니다
- 덮어쓰기 대신 새 파일. 기존 파일 위에 쓰려면
overwrite를 명시해야 합니다. - FFmpeg가 돌기 전에 검사. 필터 범위, 병합 호환성, 믹스 레벨, 오버레이 투명도, 글자 타이밍을 먼저 확인하고, 오류 메시지는 다시 시도할 정확한 호출로 끝납니다.
- 요청하지 않은 네트워크 호출 없음. 선택 모델 기능은 켜기 전까지 꺼져 있습니다. 비전·네트워크 제어를 보세요.
- 아무것도 게시하지 않습니다. Kinocut은 렌더링하고 패키징할 뿐이고, 게시는 당신 몫입니다.
하지 않는 일: Kinocut은 실제 미디어만 렌더링합니다. 텍스트→영상이나 유료 이미지 생성 어댑터는 없고, 자막 음성은 신경망 목소리가 아니라 로컬 기본 음성(eSpeak NG)을 씁니다. kinocut_sound 프로그램은 얇은 S12 결합을 제공하며, 그 벤치마크는 합성 클립 64개이지 한 편 전체도, 사람이 들어 본 승인도 아닙니다.
릴리스
| 버전 | 범위 | |
|---|---|---|
| 배포됨 (PyPI · npm · MCP Registry) | 2.0.1 (2026-11-10) | KINOCUT_TOOLS=all일 때 MCP 도구 206개, 기본 18개, CLI 명령 177개 |
| 개발 중 (미배포 #458) | 2.0.1 + video_direct | KINOCUT_TOOLS=all일 때 MCP 도구 208개, 기본 18개, CLI 명령 178개 |
| 호환 패키지 | mcp-video==1.6.22 | 옛 이름을 쓰는 사람을 위해 kinocut==2.0.1을 설치 |
PyPI에서 설치할 때: 배포된 2.0.1 패키지에는 선택 extra인 object-matte(kinocut[object-matte]==2.0.1)가 들어 있으며, MCP 도구가 새로 늘지는 않습니다.
전체 변경 내역: CHANGELOG.md · 배포본 PyPI의 2.0.1
| 소스 | GitHub(기준) · Forgejo(하위 미러) |
| MCP Registry | tech.kyanitelabs/kinocut |
| PyPI | kinocut |
| 사이트 | kinocut.dev |
| 실행 환경 | macOS, Linux, Windows · Python 3.11+ · FFmpeg |
mcp-video에서 오셨다면
이 프로젝트는 2026-07-10까지 mcp-video라는 이름이었습니다. 옛 import(mcp_video), 명령(mcp-video), MCP_VIDEO_* 변수, ~/.mcp-video 데이터 폴더는 여전히 동작합니다. 새로 설정한다면 kinocut, from kinocut import Client, kino를 쓰세요. 이름 변경 안내를 보세요.
공개 MCP 주소가 필요하다면
공유기 포트를 열지 않고 공개 MCP URL을 쓰고 싶다면 hyperframes-selfhost가 있습니다. 커뮤니티가 만든 Apache-2.0 참고 스택(Tailscale Funnel, Caddy, Google OAuth)이며 KyaniteLabs와 관련이 없으니, 내 위협 모델에 맞춰 검토하세요.
개발
git clone https://github.com/KyaniteLabs/kinocut.git
cd kinocut
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest -q -m "not slow and not hyperframes"
기여 안내 · 테스트 · 보안 · 지원 · 운영 방식 · 메인테이너 · 행동 강령 · 로드맵
기여자
Kinocut은 핵심 팀 바깥 사람들이 보낸 코드와 날카로운 버그 제보 덕분에 나아지고 있습니다. 재현 절차와 실제 트레이스백이 담긴 제보도 기여이며, 모두 여기와 CHANGELOG에 이름이 올라갑니다.
- @guillaume-hestia-projekt:
kinocut.Client로 개발하며 재현 가능한 버그 제보 19건(#546–#578)과 수정: FFmpeg 자식 프로세스가 stdin을 물려받지 않게(#559), composite-layers 캔버스 fps(#558), 정직한normalize_audio(#569)가 1.15.3에 실렸습니다. 크롭·트림·노이즈 플로어·한 번에 믹싱·시간 지정 레이어 패치는 1.16.0(#586)에 반영됐습니다. - @WohaibHasan: 트림 끝 절대값 처리(#493), Windows 드라이브 유지(#496), 이식 가능한 UTF-8 CLI 테스트 캡처(#498).
- @Beritwu: 유리수 프레임 레이트와 목록 입력을 지원하는 프레임 정확
create-from-images(#616, 1.16.2), 선택형 정밀 프로브(#599, 1.16.5). - @cnw-L: lavfi
movie=필터에서 Windows 드라이브 경로가 유지되도록(#532), 1.15.3에 실림. - @gerardoscaglia-creator: 1.15.0에서 고친 진단 공백 두 가지를 드러낸 Windows MCP 모드 조사(#445)와 함께 실린 이식 가능한 파일 잠금 수정(#446).
- @pedropaav-art: Windows 필터 옵션 경로 이스케이프(#458), 1.15.0에 실림.
- @linhaixin45-cmyk: 설치 안내가 보이는
kino doctor파이썬 버전 하한(#459), 1.15.0에 실림. - @betsmayank: 처음 병합된 외부 수정으로, TTY 없는 MCP에서 Hyperframes
init이 멈추지 않게(#361). - @AnttonioAzevedo: 무음 제거가 손상된 MP4를 쓰는 문제를 발견(#467, #506에서 수정).
- @Mimatovitch: macOS 프로세스 정리 회귀를 제보(#594), 1.16.1에서 수정(#596).
- @Zoroassistant23: #594를 조사하고 macOS 확인과 회귀 테스트가 든 패치를 제안(#595).
- @austinwmson, @ismailkattakath: 실제 공백을 메운 제보,
remotion_still런타임 props(#306)와 셀프호스트 참고 스택(#432). - @Dodothereal, @OyaAIProd(계정 삭제됨): 세로 영상 번인용 ASS PlayRes(#378) 등 초기 외부 PR.
라이선스
Apache 2.0. LICENSE를 보세요. FFmpeg, Hyperframes, Model Context Protocol 위에 만들었습니다.
Simon Gonzalez De Cruz가 KyaniteLabs에서 만들었습니다. 형제 프로젝트: Epoch(에이전트용 시간 추정), DialectOS(스페인어 방언 현지화), checkyourself(AI로 만든 코드의 배포 준비 점검). Kinocut이 편집 시간을 아껴 주었다면: ko-fi.com/kyanitelabs.