Final Cut Pro CLI / MCP

macOS에서 설치된 Final Cut Pro를 로컬 CLI 또는 MCP 서버로 감싸서, 사람이 직접 누르지 않고도 AI가 작업을 호출할 수 있게 만드는 프로젝트입니다.

용도

이 프로젝트는 이런 경우를 위한 것입니다.

• Final Cut Pro는 이미 설치되어 있고, AI에게 반복 작업을 시키고 싶은 경우
• 영상 편집을 자세히 모르지만 자연어로 AI에게 시켜서 작업 흐름을 단순화하고 싶은 경우
• Final Cut Pro의 현재 상태를 읽고, 프로젝트나 라이브러리를 확인하고, FCPXML을 가져오는 작업을 자동화하고 싶은 경우

핵심 개념은 단순합니다.

• Final Cut Pro가 먼저 Mac에 설치되어 있어야 합니다.
• 이 프로젝트가 Final Cut Pro와 통신하는 CLI/MCP 레이어 역할을 합니다.
• AI는 Final Cut Pro를 직접 아는 것이 아니라, 이 도구가 노출한 명령이나 MCP tool을 통해 Final Cut Pro를 조작합니다.

즉 구조는 아래와 같습니다.

AI client
  -> this CLI / MCP server
  -> Final Cut Pro on your Mac

현재 가능한 것

현재 구현은 Final Cut Pro에서 공식적으로 확인되는 자동화 표면에 맞춰져 있습니다.

• 설치된 Final Cut Pro 앱 감지
• Final Cut Pro 실행
• 환경/권한 점검(doctor)
• 라이브러리, 이벤트, 프로젝트 읽기
• .fcpxml 파일 import
• 5초 타이틀 전용 프로젝트 생성
• 멀티 세그먼트 스토리보드 프로젝트 생성

이 프로젝트는 아직 Final Cut Pro 전체 편집 기능을 직접 제어하는 수준은 아닙니다. 현재 Apple Events 사전은 읽기 중심이라서, 깊은 편집 자동화는 보통 아래 방식으로 확장해야 합니다.

• FCPXML 생성/수정
• Shortcuts 또는 workflow extensions
• Accessibility 기반 UI 자동화

언제 쓰면 좋은가

영상 편집 자체를 잘 모르는 사람도 아래처럼 쓸 수 있습니다.

• "지금 열려 있는 라이브러리와 프로젝트 목록 보여줘"
• "이 FCPXML 가져와서 프로젝트 초안 만들기"
• "AI가 현재 프로젝트 구조를 읽고 다음 작업 순서를 제안하게 하기"

즉, 편집 기술을 모두 외우는 대신 AI에게 지시하고, AI는 이 도구를 통해 Final Cut Pro에 작업을 전달하는 방식입니다.

설치 전제

먼저 아래가 준비되어 있어야 합니다.

• macOS
• Final Cut Pro 또는 Final Cut Pro Trial 설치
• Node.js 22 이상
• Final Cut Pro를 최소 1번은 직접 실행한 상태

권한도 필요합니다.

• 첫 자동화 시도 때 macOS가 Automation 권한을 물을 수 있습니다.
• 필요하면 접근성 권한도 나중에 추가로 필요할 수 있습니다.

설치 방법

cd /Users/minwokim/Documents/GitHub/final-cut-pro-mcp
npm install
npm run build

빌드 후 CLI와 MCP 엔트리는 각각 아래 파일입니다.

• dist/cli.js
• dist/mcp.js

CLI로 쓰는 방법

AI 연결 없이 로컬 명령으로만 써도 됩니다.

npm run cli -- help
npm run cli -- app-info
npm run cli -- open
npm run cli -- doctor --json
npm run cli -- list-libraries --json
npm run cli -- import-fcpxml ./example.fcpxml
npm run cli -- create-title-project --text 시작 --seconds 5
npm run cli -- create-title-project --text 시작 --seconds 5 --effect zoom
npm run cli -- create-storyboard-project --segments "시작|2|zoom;핵심|2|move;마무리|1|fade"

create-title-project에서 현재 지원하는 효과 프리셋:

• basic: 기본 타이틀 + 스케일 확대 키프레임
• zoom: Final Cut 기본 Zoom 타이틀
• fade: Final Cut 기본 Fade 타이틀
• move: Final Cut 기본 Move 타이틀

create-storyboard-project는 한 프로젝트 안에 여러 자막 컷을 순서대로 생성합니다.

• 인라인 입력: --segments "문구|초|효과;문구|초|효과"
• 파일 입력: --segments-file ./story.json

story.json 예시:

{
  "segments": [
    { "text": "시작", "durationSeconds": 2, "effectPreset": "zoom" },
    { "text": "핵심 장면", "durationSeconds": 2, "effectPreset": "move", "positionY": -120 },
    { "text": "마무리", "durationSeconds": 1, "effectPreset": "fade" }
  ]
}

CLI만 쓸 거라면 MCP는 굳이 필요 없습니다.

AI에 탑재하는 방법

AI가 이 도구를 호출하게 하려면 MCP를 쓰는 편이 맞습니다. MCP를 지원하는 AI 클라이언트에 이 서버를 등록하면, AI가 아래 tool을 통해 Final Cut Pro를 조작할 수 있습니다.

서버 실행:

npm run mcp

배포용으로 연결할 때는 보통 아래처럼 dist/mcp.js를 stdio 명령으로 등록하면 됩니다.

node /Users/minwokim/Documents/GitHub/final-cut-pro-mcp/dist/mcp.js

AI 클라이언트에서 연결되면 현재 노출되는 tool은 다음과 같습니다.

• fcp_app_info
• fcp_open
• fcp_doctor
• fcp_list_libraries
• fcp_import_fcpxml
• fcp_create_title_project
• fcp_create_storyboard_project

정리하면:

• 사람이 AI에게 자연어로 요청
• AI가 MCP tool 호출
• 이 서버가 로컬 Final Cut Pro에 명령 전달

어떤 AI에 연결할 수 있나

현재 기준으로는 아래처럼 정리하는 게 정확합니다.

• Codex: 가능. 로컬 stdio MCP 서버를 바로 등록할 수 있습니다.
• Claude Code: 가능. 로컬 stdio MCP 서버를 바로 등록할 수 있습니다.
• Gemini CLI: 가능. ~/.gemini/settings.json에 MCP 서버를 등록하는 방식입니다.
• ChatGPT 웹/앱: 부분 가능. 다만 이 프로젝트의 현재 형태인 로컬 stdio 서버를 그대로 붙일 수는 없습니다.

중요한 차이는 여기입니다.

• Codex, Claude Code, Gemini CLI는 로컬 머신에서 MCP 프로세스를 직접 실행할 수 있습니다.
• ChatGPT는 현재 앱/개발자 모드에서 MCP를 지원하지만, 공식 문서 기준으로 원격 HTTP 또는 SSE 방식이 대상입니다.

즉, 현재 이 프로젝트는 아래 세 가지에는 바로 연결됩니다.

• Codex
• Claude Code
• Gemini CLI

반대로 ChatGPT에 바로 붙이려면 추가 작업이 필요합니다.

• 현재 stdio 서버를 원격 HTTP 또는 SSE MCP 서버로 감싸기
• 또는 별도 브리지 서버를 두고 ChatGPT Apps / Developer mode로 연결하기

이건 공식 문서를 바탕으로 한 정리입니다. ChatGPT에서 MCP 자체는 이제 되지만, 이 프로젝트의 현재 로컬 stdio 형태를 그대로 연결하는 것은 맞지 않습니다.

클라이언트별 연결 방법

Codex

이미 이 Mac에서는 아래 명령으로 등록해 둔 상태입니다.

codex mcp add final-cut-pro -- node /Users/minwokim/Documents/GitHub/final-cut-pro-mcp/dist/mcp.js

확인:

codex mcp list
codex mcp get final-cut-pro

코드를 바꾼 뒤에는 다시 빌드해야 합니다.

cd /Users/minwokim/Documents/GitHub/final-cut-pro-mcp
npm run build

Claude Code

Claude Code는 로컬 stdio MCP 서버를 직접 등록할 수 있습니다.

claude mcp add --transport stdio final-cut-pro -- \
  node /Users/minwokim/Documents/GitHub/final-cut-pro-mcp/dist/mcp.js

확인:

claude mcp list
claude mcp get final-cut-pro

Gemini CLI

Gemini CLI는 공식 문서 기준으로 ~/.gemini/settings.json에서 MCP 서버를 구성합니다.

예시:

{
  "mcpServers": {
    "final-cut-pro": {
      "command": "node",
      "args": [
        "/Users/minwokim/Documents/GitHub/final-cut-pro-mcp/dist/mcp.js"
      ]
    }
  }
}

그 뒤 Gemini CLI를 실행하면 됩니다.

gemini

ChatGPT

ChatGPT도 지금은 MCP 기반 앱/커넥터를 지원합니다. 다만 이 프로젝트는 현재 로컬 stdio 서버이므로 그대로는 연결 대상이 아닙니다.

정리하면:

• ChatGPT에서 MCP 자체는 가능
• 하지만 현재 프로젝트는 ChatGPT용으로 바로 연결되는 형태는 아님
• ChatGPT에 붙이려면 원격 HTTP 또는 SSE MCP 엔드포인트가 추가로 필요

첫 번째 데모 프롬프트

사용자 입장에서 가장 직관적인 데모 문장은 이런 식이 맞습니다.

프로그램을 열어서 프로젝트 하나 파고, 자막으로 "시작" 이라는 문구로 시작되는 5초짜리 영상 만들어줘.

이제 이 문장은 실제로 처리 가능한 프롬프트입니다.

현재 구현으로 바로 가능한 프롬프트:

• Final Cut Pro 열어줘
• 지금 상태 점검해줘(doctor 실행)
• 현재 라이브러리와 프로젝트 구조 읽어줘
• 이 FCPXML 가져와줘: /절대/경로/example.fcpxml
• 무제 라이브러리에 프로젝트 하나 만들고, 시작이라는 문구가 들어간 5초짜리 타이틀 프로젝트 만들어줘
• 3컷 스토리보드로 만들어줘: 시작(2초, zoom), 핵심(2초, move), 마무리(1초, fade)

이 타이틀 프로젝트 생성은 내부적으로 아래 방식으로 동작합니다.

• Final Cut Pro용 FCPXML 생성
• 기존 .fcpbundle 라이브러리 지정 import
• 5초 시퀀스와 텍스트 타이틀 프로젝트 생성

다만 아직 아래 단계는 별도 구현이 필요합니다.

• 타임라인 세부 편집
• 실미디어(영상/오디오) 자동 배치 및 컷 편집
• 최종 영상 export

추천 사용 시나리오

예를 들어 실제 편집을 잘 모르는 사용자는 이런 식으로 쓸 수 있습니다.

• "Final Cut Pro 열고 현재 라이브러리 구조부터 읽어줘"
• "내가 준 FCPXML을 가져와서 초안 프로젝트를 준비해줘"
• "프로젝트 이름과 구조를 보고 다음 편집 순서를 정리해줘"

이 프로젝트는 "AI가 편집자를 완전히 대체한다"기보다, "Final Cut Pro의 반복 작업과 준비 작업을 AI가 대신 처리하게 만든다"는 용도에 가깝습니다.

주의사항

• list-libraries는 Final Cut Pro가 열려 있지 않거나 Automation 권한이 없으면 타임아웃될 수 있습니다.
• 처음에는 Final Cut Pro를 한 번 직접 열고 권한 요청을 허용하는 편이 안전합니다.
• import-fcpxml은 open -a "<Final Cut Pro>" <file> 방식으로 동작합니다.