Claude로 CapCut 사용하기

CapCut MCP는 Codex용으로 제작되었습니다. 이 스킬은 Claude에 맞게 조정한 것입니다. 공식 자료는 official/ 디렉토리에 그대로 보관되어 있으며(플러그인 v0.2.6), 이 파일은 여기서 사용하는 방법과 실제 사용 시 검증된 내용(2026-10-26/27, Claude 데스크톱 Code 탭, Windows)을 설명합니다.

아래 경로는 이 스킬 폴더(~/.claude/skills/capcut/)를 기준으로 합니다.

official/ 디렉토리가 없는 경우(새로 클론한 경우), 먼저 python scripts/fetch_official.py를 실행하세요. 이 스크립트는 CapCut의 CDN에서 플러그인 번들을 다운로드합니다(공식 자료는 이 저장소에 재배포되지 않습니다). --force 플래그를 사용하면 최신 게시 버전으로 새로고침합니다.

0. 연결 (도구가 없거나 실패하는 경우 먼저 수행)

연결할 수 있는 유일한 방법은 Claude 데스크톱 설정에서 mcp-remote를 통한 로컬 MCP 서버입니다. CapCut을 claude.ai 커스텀 커넥터로 추가하는 것은 작동하지 않습니다. CapCut의 OAuth 서버가 Claude의 동적 클라이언트 등록을 거부하기 때문입니다( "无法在 CapCut 的登录服务中注册"). 또한 클라이언트 ID를 제공할 수 없습니다.

%LOCALAPPDATA%\Claude-Data\<profile>\claude_desktop_config.json (또는 %APPDATA%\Claude\claude_desktop_config.json) → mcpServers:

"capcut":          {"command": "cmd", "args": ["/c", "npx", "-y", "mcp-remote", "https://www.capcut.com/api/external_mcp"]},
"capcut_resource": {"command": "cmd", "args": ["/c", "npx", "-y", "mcp-remote", "https://www.capcut.com/api/external_mcp/resource"]}

capcut = 계정 기반 도구(OAuth). capcut_resource = 신원이 필요 없는 카드 도구(로그인 불필요). 편집 전에 설정을 백업하세요. 사용자는 편집 후 Claude를 완전히 종료하고 다시 열어야 합니다.

처음부터 설정 (세션에 mcp__capcut__* 도구가 없는 경우):

필수 조건 확인: node --version (≥14) 및 PATH에 npx가 있는지 확인합니다.
활성 설정 파일 찾기: 먼저 %LOCALAPPDATA%\Claude-Data\*\claude_desktop_config.json을 검색한 다음 %APPDATA%\Claude\claude_desktop_config.json을 검색합니다. 파일을 읽고 claude_desktop_config.json.bak-<날짜>로 복사한 후, 다른 내용은 건드리지 않고 mcpServers 아래에 두 항목을 추가하고(키가 없으면 생성), JSON으로 다시 구문 분석하여 유효한지 확인합니다.
사용자에게 시스템 기본 브라우저에서 초안이 저장될 CapCut 계정으로 로그인하도록 요청한 다음, Claude를 완전히 종료(트레이 아이콘 → 종료)하고 다시 열도록 합니다.
시작할 때 mcp-remote가 해당 브라우저에서 CapCut 인증 페이지를 엽니다. 사용자가 승인합니다(즉시 깜빡이고 닫히면 자동 승인된 것입니다 — 문제 없음).
현재 세션은 시작된 후 추가된 서버를 볼 수 없습니다. 새로운 Code 탭 세션에서 계속 진행합니다. start_stdraft_session( session_id 반환) 및 search_capcut_material (type: music)으로 확인합니다.
선택 사항: Claude의 내장 브라우저를 동일한 CapCut 계정에 로그인하여 초안을 검사할 수 있도록 합니다.

OAuth 토큰은 ~/.mcp-auth/mcp-remote-v1/<hash>_tokens.json 및 <hash>_client_info.json에 캐시됩니다.
재인증 / 계정 전환: 먼저 사용자에게 물어보십시오. 위 두 파일을 삭제합니다. 사용자가 다시 시작하기 전에 원하는 CapCut 계정(동일한 로그인 방식 — Google/이메일/TikTok은 다른 계정)에 시스템 기본 브라우저로 로그인합니다. 그런 다음 Claude를 완전히 종료하고 다시 엽니다. mcp-remote가 CapCut 인증 페이지를 엽니다(해당 브라우저가 이미 로그인된 경우 깜빡이고 닫힐 수 있습니다 — 성공입니다). start_stdraft_session으로 확인합니다.
모든 호출에서 get user workspace failed: check login error 증상 = 캐시된 권한이 만료됨 → 위와 같이 재인증합니다.
재인증하면 동일한 계정이 다른 CapCut 웹 세션(Claude의 내장 브라우저 포함)에서 로그아웃됩니다. 사용자는 거기에 다시 로그인해야 합니다.
초안은 MCP가 인증된 계정에 저장됩니다. 사용자가 초안을 볼 수 없으면 먼저 계정을 비교하십시오.

1. 작동하는 표면

표면	상태
Claude 데스크톱 Code 탭 세션	아래 모든 기능이 작동합니다. CapCut 작업에는 이것을 사용하십시오.
Code 탭 세션을 원격 제어하는 휴대폰	Code 탭과 동일합니다(도구가 PC에서 실행됨).
데스크톱 채팅 / PC 도구에 접근하는 휴대폰 채팅	초안 도구가 "session_id 누락"으로 실패합니다(브리지가 말 그대로 `session_id`라는 매개변수를 드롭하는 것으로 보입니다). 카드가 표시되지 않을 수 있습니다. 거기서 초안 편집을 하지 마십시오.
자체 휴대폰 채팅	CapCut이 전혀 없습니다(서버가 PC에 로컬입니다).

카드(capcut_resource: templates_preview_v2, editing_plan, video_preview, background_music, billing_confirmation)는 가져오지만 Code 탭에서는 렌더링되지 않습니다. 결과는 텍스트/JSON으로 도착합니다. 카드를 기다리지 말고 데이터를 읽고 직접 표시하십시오.

2. 읽어야 할 공식 문서 (작업에 필요한 것만)

초안 작업을 위해 반드시 읽어야 할 문서: official/capcut-stdraft-builder/reference/application.md (함수 계약). 다른 것은 작업과 관련될 때만 읽으십시오.

작업	읽을 문서
러프 컷 핸드오프 또는 기존 비디오의 캡션	`official/video-editing/references/post-editing.md`
세션/버전/푸시/충돌	`official/web-collaborative-editing/SKILL.official.md` (+ `references/conflict-recovery.md`)
필드 수준 프로토콜 질문	`official/capcut-stdraft-builder/reference/STDraft_Protocol.md`, `validation.md`
자료	`official/video-editing/references/materials.md`
캡션	`official/video-editing/references/auto-captions.md`
AI 러프 컷	`official/video-editing/references/ai-rough-cut.md`
이미지/동영상 생성	`official/generate-media/SKILL.official.md` + `references/`
템플릿 검색	`official/search-templates/SKILL.official.md`

Codex 전용 부분은 무시하십시오: codex plugin 설치/업그레이드, codex app-server/capcut-login.mjs OAuth, "New-Task Handoff"/포크, require_escalated 샌드박스 플래그, TTY 티켓 입력, "카드 후 자동으로 턴 종료".

3. 핵심 워크플로우: 클라우드 초안 빌드/편집

셸: Bash 도구(Git Bash)에서 명령어를 실행하십시오. PowerShell을 사용하지 마십시오. Windows 경로는 슬래시(D:/proj/clip.mp4) 또는 작은따옴표로 묶어 사용하십시오. 업로드 맵과 초안이 세션 간에 유지되도록 사용자의 프로젝트 폴더(예: <project>/capcut_work/)에서 작업하십시오.

로컬 미디어 업로드는 공식 업로더만 사용하십시오(직접 만든 VOD 코드 사용 금지):
- capcut_asset_upload_credential을 version: 2 및 files: [{file_name, size_bytes}]와 함께 전체 배치에 대해 호출 → upload_ticket(수명이 짧은 단일 배치 기능이며, 이 대화에서 한 번만 전달되어야 합니다. 절대 다른 곳에 기록하지 마십시오).
- 티켓을 줄바꿈 문제 없이 작성하고, stdin으로 파이프하고(argv에 절대 넣지 마십시오), 파일을 삭제하십시오:
```
cd <project>/capcut_work && printf '%s\n' '<ticket>' > ticket.tmp
node ~/.claude/skills/capcut/official/capcut-upload/scripts/capcut-upload.mjs \
  --files '[{"client_id":"c1","file":"D:/proj/a.mp4"},{"client_id":"c2","file":"D:/proj/b.mp3"}]' \
  --upload-ticket-stdin --json < ticket.tmp > upload_result.json 2> upload_stderr.txt; rm -f ticket.tmp
```
  (단일 파일: --file <path> --client-id c1; 진행률 → stderr, JSON → stdout.)
- 성공 = 비어 있지 않은 vid 그리고 setPublic.success:true. name → {vid, duration} 맵(upload_map.json)을 저장하십시오. 이미 vid가 있는 항목은 다시 업로드하지 마십시오. 티켓은 약 1시간 후에 만료됩니다.
세션: 초안당 한 번 start_stdraft_session을 호출하고 session_id를 유지하십시오. 각 편집 라운드 전에 check_stdraft_state(session_id, local_package_id)를 호출하십시오:
- 완전히 새로운 초안: "" 전달; server_package_id:"" 예상 → 처음부터 빌드하고 base_package_id:""로 푸시;
- 그렇지 않으면 official/web-collaborative-editing/SKILL.official.md의 기준선 표를 따르십시오(오래된 경우 먼저 get_stdraft_snapshot 호출).
로컬로 빌드는 공식 원자 함수(Python ≥3.8, stdlib만 사용, python -B, sys.path.insert(0, "C:/Users/<user>/.claude/skills/capcut/official/capcut-stdraft-builder/scripts")로 실행)를 사용하십시오: apply_video, apply_audio, apply_text, apply_text_template, apply_captions, apply_video_effect, apply_filter, apply_transition, update_material, update_placement, update_caption_text, remove_material, unset_attribute. result["draft"]를 연결하십시오. 새 초안 루트: {"version":"0.1.0","segments":[{"id":"draft","type":"DRAFT","attributes":{"width":1920,"height":1080,"ratio_type":"16:9"}}]}.
- 클립 음소거: apply_video(..., volume=0.0). 시간은 정수 밀리초(ms)입니다.
- 모든 vid/sid 소스에 대해 SOURCE_RANGE_UNVERIFIED가 발생합니다 — 예상된 현상입니다. 직접 확인하십시오: source_start_ms + duration_ms × speed는 소스 길이(upload_map.json의 값 또는 음악 검색 결과의 duration_ms)를 초과하지 않아야 합니다.
- 검색 결과 선택: duration_ms가 필요한 길이를 포함하고 제목/캡션이 분위기에 맞는 항목을 선호하십시오. 선택한 항목을 명시하십시오.
푸시 준비: python -B ~/.claude/skills/capcut/scripts/draft_tool.py slim draft.json draft_slim.json 실행(짧은 ID, 줄당 하나의 세그먼트, 재검증, ~60k자 초과 시 경고). draft_slim.json을 읽고 전체 텍스트를 그대로 push_stdraft_snapshot의 stdraft_json에 붙여넣으십시오(크기의 두 배에 해당하는 토큰이 소모되므로 초안을 간결하게 유지하십시오).
푸시 후: 결과가 harness에 의해 파일로 저장된 경우 draft_tool.py summary <file> / urls <file>을 실행하십시오. 인라인으로 반환된 경우 먼저 push_result.json에 저장하거나 파이프(... summary -)하십시오. 사용자에게 web_editor_url을 web_editor_text(서버 로케일, 예: "Buksan sa CapCut")를 레이블로 하는 마크다운 링크로 제공하십시오. 반환된 stdraft_json/server_package_id를 다음 기준선으로 사용하십시오.
- 일반적인 서버 재작성(오류 아님): vid:// → asset://<id>; DRAFT는 무작위 ID를 얻고 ratio_type을 잃습니다. 레이어가 번호가 다시 매겨집니다. end.ms가 모든 곳에 추가됩니다. TEXT는 font_color/line_max_width와 PATCH 자식("스타일 복사")을 얻습니다. VIDEO는 crop/background.* 기본값을 얻습니다. AUDIO meta_type은 소문자가 됩니다. 콘텐츠, 타이밍, 볼륨, 속도, 전환 및 키프레임을 비교하십시오 — ID나 레이어 번호는 비교하지 마십시오.
선택적으로 내장 브라우저에서 embed_editor_url을 열어 볼 수 있습니다. 해당 브라우저가 동일한 CapCut 계정에 로그인된 경우에만 작동합니다. 대규모 프로젝트는 로드하는 데 30-60초가 걸릴 수 있습니다. 텍스트는 세그먼트를 선택한 후에만 그려질 수 있습니다.

푸시 문제점 (검증됨)

시간 초과 ≠ 실패. 새 계정에 처음 푸시하면 모든 미디어 파일이 복사되므로 클라이언트 시간 초과를 초과하면서도 성공할 수 있습니다. 절대 맹목적으로 다시 푸시하지 마십시오. 먼저 check_stdraft_state를 호출하십시오. 버전이 존재하면 get_stdraft_snapshot(draft_tool을 통해 요약)을 호출하고 그로부터 계속하십시오. 맹목적인 재푸시는 STDRAFT_VERSION_CONFLICT를 반환합니다.
시간 초과된 푸시로 생성된 초안은 라이브러리에 표시되지 않을 수 있으며 URL을 반환하지 않습니다. 그 위에 한 번 더 푸시(동일한 콘텐츠, 올바른 기준선)하면 편집기 URL이 반환됩니다.
크기: ~55k자는 안정적으로 푸시됩니다. ~90k자는 한 번의 호출에 맞지 않았습니다. 푸시를 간결하게 유지하십시오(선택적 키프레임/스타일 생략, 웹 편집기에서 추가).

4. 검증된 기능 경계

작동하고 클라우드 저장이 유지되는 기능: 비디오 클립(소스 인포인트, 지속 시간, 볼륨, 속도), 전환(추가/교체/제거, 동일 레이어, 연속), 음악 및 효과음(sid:// 검색 또는 자체 vid://, 볼륨, 자동 루프 없음), 강도가 있는 필터, 일반 텍스트(글꼴, 크기, 색상, 위치, 테두리), 글꼴 교체, 텍스트 효과(flower), 텍스트 템플릿(서버가 IN 애니메이션 추가, 슬롯 수 확인 불가), 단어 타이밍이 있는 캡션 및 update_caption_text, 제거/설정 해제, 배치/레이어/타이밍 변경, scale_*/alpha 키프레임 속도가 1인 클립에서만.

저장 시 손실되거나 깨짐:

VIDEO_EFFECT 세그먼트(비디오 효과 및 얼굴 효과)는 완전히 삭제됩니다 — 웹 편집기에서 효과를 추가하도록 사용자에게 알리십시오.
speed ≠ 1인 클립의 키프레임은 시간이 속도에 따라 재조정되고 대부분 삭제됩니다.
빌더가 다루지 않는 모든 것(마스크, 스티커, 곡선, 그레이딩)은 웹 편집기에서 수행해야 합니다.
MCP를 통한 내보내기/렌더링은 불가능합니다. 사용자는 CapCut 편집기에서 내보냅니다.

자료 검색: music, sound_effect, video_effect는 프롬프트를 따릅니다. font, text_effect, text_template, face_effect, transition, filter는 프롬프트와 관계없이 고정된 선별된 목록(최대 20개)을 반환합니다. 일반적인 cross-dissolve는 없습니다. 선별된 글꼴은 라틴어입니다(중국어는 기본 글꼴 vimo://7317175475195875841로 대체되며 CJK를 렌더링합니다). 비디오 푸티지/이미지는 검색할 수 없습니다 — 업로드하십시오.

자동 캡션(auto_caption_submit / auto_caption_query): 음성 인식만 가능합니다. Pro 멤버십이 필요합니다(무료 계정은 PAYWALL_REQUIRED 반환 — benefit_check_label 링크를 그대로 표시하십시오). 노래 가사에는 쓸모없음(전체 노래가 하나의 쓰레기 줄로 반환됨) — 가사 타이밍에는 로컬 Whisper + 알려진 가사를 대신 사용하십시오.

템플릿 검색: capcut_template_search → capcut_template_search_poll_v2를 터미널 상태가 될 때까지 폴링 → templates_preview_v2(search_id)가 템플릿 데이터를 반환합니다(카드 렌더링 안 됨, 사용자를 위해 제목, 지속 시간, 사용량 및 page_url을 나열). 관련성은 느슨합니다. 결과는 15일 동안 지속됩니다. 최대 10개.

AI 러프 컷(AI Lab): capcut_ailab_start_edit(assets=[{resource_id: <vid>, file_name}], query) → 폴링 → loop_turn_completed 상태의 계획 이벤트 도착, 계획을 사용자에게 전달한 다음 capcut_ailab_submit_plan_response를 card_id 없이(계획의 이벤트 ID는 plan_card_id_invalid로 거부됨) 사용자의 정확한 선택 텍스트와 함께 호출합니다. 음악 및 최종 비디오 이벤트가 뒤따릅니다(10초 컷의 경우 약 2분). 최종 이벤트의 context/resources를 변경하지 않고 video_preview를 호출하여 결과의 편집 가능한 STDraft(stdraft 필드)를 얻습니다. 이를 초안 세션으로 가져와 계속 편집합니다. 오디오 전용 자산은 거부됩니다(unsupported_edit_file_name). 캡션 전용 요청에는 AI Lab을 사용하지 마십시오.

이미지/동영상 생성(Seedream / Seedance): 크레딧을 소비합니다. 여기서 카드가 렌더링되지 않으므로: confirmed:false로 제출(unique_key 없음) → CONFIRMATION_REQUIRED 발생 시 사용자에게 정확한 credits_amount를 알림 → 사용자가 채팅에서 해당 금액을 명시적으로 승인한 후에만 반환된 unique_key/동일한 generate_id로 confirmed:true를 다시 시도합니다. 사용자를 대신하여 절대 확인하지 마십시오. next_action=none이 될 때까지 capcut_generation_poll을 폴링한 후 generation_result(task_id)로 결과를 가져옵니다(비디오: videos 배열의 각 요소에 대해 video_preview(task_id, resource_type: "video", resources: [{resource_id, file_name, ext}])를 호출하여 stdraft 필드를 추출). 요청당 크레딧 비용은 초안에 포함시킬 수 없습니다 — 사용자에게 수동으로 알리십시오. 사용자가 생성하는 각 이미지/비디오가 그렇게 승인되어야 합니다.

5. 문제 해결

증상	조치
CapCut MCP 도구가 전혀 보이지 않음	설정 확인 → Claude 종료/재시작 → 새 Code 탭 세션. 그래도 보이지 않으면 `mcp-remote`가 전역 `npx` 경로에 있는지 확인하십시오.
모든 호출에서 `get user workspace failed`	캐시된 OAuth 만료 → 시스템 기본 브라우저에서 CapCut 계정에 로그인하고, 캐시된 파일 삭제, Claude 종료/재시작, 승인, 새 Code 탭 세션에서 확인.
`STDRAFT_VERSION_CONFLICT`	`check_stdraft_state` 호출, `get_stdraft_snapshot`, `draft_tool.py summary`로 현재 상태 확인, 거기서 계속 빌드.
`PAYWALL_REQUIRED` (자동 캡션)	Pro 필요. `benefit_check_label` 링크 전달.
템플릿 검색 결과가 적거나 관련 없음	고정된 선별된 목록만 반환됨. 키워드를 최대한 구체적으로 지정.
AI Lab이 "unsupported file" 오류 반환	오디오 전용 파일은 지원되지 않습니다. 비디오 파일을 사용하십시오.
이미지/비디오 생성에서 "CONFIRMATION_REQUIRED"	사용자에게 크레딧 비용을 알리고 명시적 승인을 받으십시오.

6. 모범 사례

업로드 맵 유지: upload_map.json에 vid를 저장하여 재업로드를 방지합니다. 티켓은 1시간 후에 만료됩니다.
작업 유지: 각 세션에서 변경 사항을 점진적으로 빌드합니다. 모든 것을 한 번에 푸시하지 마십시오.
푸시 확인: 각 푸시 후 check_stdraft_state를 호출하고 draft_tool.py summary를 사용하여 서버가 초안을 어떻게 해석하는지 확인하십시오.
새로운 세션에서 시작: 설정 변경 후에는 항상 새 Code 탭 세션을 사용하십시오.
웹 편집기 사용: VIDEO_EFFECT, 마스크, 스티커, 곡선 및 그레이딩과 같이 MCP에서 지원하지 않는 기능은 사용자에게 웹 편집기에서 수행하도록 안내하십시오.
크레딧 확인: 생성 요청은 사용자가 직접 확인한 후에만 제출하십시오.
문서 참조: 특정 작업의 경우 항상 관련 공식 문서를 먼저 읽으십시오.

7. 알려진 제한 사항

Codex 전용: 설치/업그레이드, OAuth 플로우(대신 mcp-remote 사용), 포크, 샌드박스 플래그, 카드 렌더링은 Codex 전용이므로 이 스킬에서는 사용할 수 없습니다.
카드 렌더링 안 됨: Code 탭에서 결과는 JSON으로 도착합니다. 직접 구문 분석하여 표시하십시오.
내보내기 불가능: MCP는 렌더링/내보내기를 지원하지 않습니다. 사용자는 CapCut 편집기에서 내보냅니다.
프로젝트 크기 제한: ~55k자까지 안정적으로 푸시됩니다. 더 큰 초안은 여러 번 푸시하거나 웹 편집기에서 축소하십시오.
계정 바인딩: 모든 초안은 MCP가 인증된 CapCut 계정에 저장됩니다. 계정을 전환하려면 재인증이 필요합니다.

capcut-claude-skill