capcut-claude-skill

CapCut von Claude aus

Das CapCut MCP wurde für Codex entwickelt. Diese Skill ist die Claude-Adaption: Das offizielle Material bleibt wörtlich unter official/ (Plugin v0.2.6), und diese Datei beschreibt, wie es hier verwendet wird, sowie was in der Praxis verifiziert wurde (2026-10-26/27, Claude Desktop Code Tab, Windows).

Pfade unten sind relativ zum Ordner dieser Skill (~/.claude/skills/capcut/).

Wenn official/ fehlt (frischer Klon), führen Sie zuerst python scripts/fetch_official.py aus – es lädt CapCuts Plugin-Bundle von CapCuts CDN herunter (das offizielle Material wird in diesem Repository nicht weiterverteilt). --force aktualisiert es auf die neueste veröffentlichte Version.

0. Verbindung (zuerst tun, wenn Tools fehlen oder fehlschlagen)

Die einzige funktionierende Verbindungsmethode sind lokale MCP-Server in der Konfiguration von Claude Desktop, mittels mcp-remote. Das Hinzufügen von CapCut als benutzerdefinierten Connector auf claude.ai funktioniert NICHT: CapCuts OAuth-Server lehnt Claudes dynamische Client-Registrierung ab ("无法在 CapCut 的登录服务中注册"), und eine Client-ID kann nicht bereitgestellt werden.

%LOCALAPPDATA%\Claude-Data\<Profil>\claude_desktop_config.json (oder %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 = kontogebundene Tools (OAuth). capcut_resource = identitätsfreie Kartentools (kein Login). Erstellen Sie ein Backup der Konfiguration vor der Bearbeitung; der Benutzer muss Claude nach der Bearbeitung vollständig beenden und neu öffnen.

Einrichtung von Grund auf (keine mcp__capcut__*-Tools in der Sitzung):

1. Prüfen Sie die Voraussetzungen: node --version (≥14) und npx im PATH.
2. Finden Sie die Live-Konfiguration: Suchen Sie zuerst %LOCALAPPDATA%\Claude-Data\*\claude_desktop_config.json, dann %APPDATA%\Claude\claude_desktop_config.json. Lesen Sie sie, kopieren Sie sie nach claude_desktop_config.json.bak-<Datum>, fügen Sie die beiden Einträge unter mcpServers hinzu (erstellen Sie den Schlüssel, falls nicht vorhanden), ohne etwas anderes zu ändern, und parsen Sie die Datei erneut als JSON, um zu bestätigen, dass sie gültig ist.
3. Bitten Sie den Benutzer, sich im systemweiten Standardbrowser in das CapCut-Konto einzuloggen, in dem die Entwürfe gespeichert werden sollen, dann Claude vollständig zu beenden (Tray-Symbol → Beenden) und neu zu öffnen.
4. Beim Start öffnet mcp-remote die CapCut-Autorisierungsseite in diesem Browser; der Benutzer genehmigt (ein sofortiges Aufblitzen und Schließen bedeutet, dass es automatisch genehmigt wurde – in Ordnung).
5. Die aktuelle Sitzung kann Server, die nach ihrem Start hinzugefügt wurden, nicht sehen: Fahren Sie in einer neuen Code-Tab-Sitzung fort. Verifizieren Sie dort mit start_stdraft_session (sollte eine session_id zurückgeben) und search_capcut_material (type: music).
6. Optional: Melden Sie Claudes integrierten Browser im selben CapCut-Konto an, damit Entwürfe dort inspiziert werden können.

• OAuth-Token werden zwischengespeichert in ~/.mcp-auth/mcp-remote-v1/<hash>_tokens.json und <hash>_client_info.json.
• Neu autorisieren / Konto wechseln: Fragen Sie zuerst den Benutzer; löschen Sie diese beiden Dateien; der Benutzer meldet sich im systemweiten Standardbrowser im gewünschten CapCut-Konto an (gleiche Anmeldemethode – Google/E-Mail/TikTok sind verschiedene Konten) vor dem Neustart; dann beenden Sie Claude vollständig und öffnen es neu; mcp-remote öffnet die CapCut-Autorisierungsseite (es kann aufblitzen und schließen, wenn dieser Browser bereits angemeldet ist – das ist Erfolg). Verifizieren Sie mit start_stdraft_session.
• Symptom get user workspace failed: check login error bei jedem Aufruf = das zwischengespeicherte Grant ist abgelaufen → neu autorisieren wie oben.
• Die Neuautorisierung meldet dasselbe Konto von anderen CapCut-Websitzungen ab (einschließlich Claudes integriertem Browser); der Benutzer muss sich dort erneut anmelden.
• Entwürfe werden in dem Konto gespeichert, für das das MCP autorisiert ist. Wenn der Benutzer einen Entwurf nicht sehen kann, vergleichen Sie zuerst die Konten.

1. Welche Oberfläche funktioniert

Oberfläche	Status
Claude Desktop Code Tab-Sitzung	Alles unten funktioniert. Verwenden Sie dies für CapCut-Arbeit.
Telefon fernsteuernd eine Code-Tab-Sitzung	Wie Code Tab (Tools laufen auf dem PC).
Desktop Chat / Telefon-Chat erreicht die PC-Tools	Entwurfstools schlagen fehl mit "missing session_id" (die Brücke scheint einen Parameter namens session_id zu verlieren); Karten werden möglicherweise nicht angezeigt. Keine Entwurfsbearbeitung dort durchführen.
Telefon-Chat allein	Kein CapCut (Server sind lokal auf dem PC).

Karten (capcut_resource: templates_preview_v2, editing_plan, video_preview, background_music, billing_confirmation) werden abgerufen, aber nicht gerendert im Code Tab – Ergebnisse kommen als Text/JSON. Warten Sie niemals auf eine Karte; lesen Sie die Daten und präsentieren Sie sie selbst.

2. Offizielle Dokumente zum Lesen (nur was die Aufgabe benötigt)

Pflichtlektüre für jede Entwurfsarbeit: official/capcut-stdraft-builder/reference/application.md (Funktionsverträge). Alles andere nur, wenn die Aufgabe es berührt.

Aufgabe	Lesen
Rohschnitt-Übergabe oder Untertitel auf vorhandenem Video	official/video-editing/references/post-editing.md
Sitzung/Version/Push/Konflikte	official/web-collaborative-editing/SKILL.official.md (+ references/conflict-recovery.md)
Feldprotokollfragen	official/capcut-stdraft-builder/reference/STDraft_Protocol.md, validation.md
Materialien	official/video-editing/references/materials.md
Untertitel	official/video-editing/references/auto-captions.md
KI-Rohschnitt	official/video-editing/references/ai-rough-cut.md
Bild-/Videogenerierung	official/generate-media/SKILL.official.md + references/
Vorlagensuche	official/search-templates/SKILL.official.md

Codex-spezifische Teile ignorieren: codex plugin Installation/Upgrade, codex app-server/capcut-login.mjs OAuth, "New-Task Handoff"/fork, require_escalated Sandbox-Flags, TTY-Ticket-Eingabe, "end the turn silently after a card".

3. Kern-Workflow: Cloud-Entwurf erstellen/bearbeiten

Shell: Befehle im Bash-Tool (Git Bash) ausführen, nicht PowerShell. Verwenden Sie Windows-Pfade mit Vorwärtsschrägstrich (D:/proj/clip.mp4) oder in einfachen Anführungszeichen. Arbeiten Sie im Projektordner des Benutzers (z.B. <project>/capcut_work/), damit Upload-Maps und Entwürfe die Sitzung überleben.

1. Lokale Medien hochladen nur mit dem offiziellen Uploader (niemals selbstgestrickter VOD-Code):
   • capcut_asset_upload_credential mit version: 2 und files: [{file_name, size_bytes}] für den gesamten Batch → upload_ticket (eine kurzlebige Single-Batch-Fähigkeit; sie durchläuft notwendigerweise dieses Gespräch einmal – niemals woanders protokollieren).
   • Schreiben Sie das Ticket ohne Probleme mit abschließenden Zeilenumbrüchen, leiten Sie es über stdin (niemals in argv), löschen Sie die Datei:

     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
     

     (Einzelfall: --file <pfad> --client-id c1; Fortschritt → stderr, JSON → stdout.)
   • Erfolg = nicht-leeres vid und setPublic.success:true. Speichern Sie eine name → {vid, duration}-Map (upload_map.json); laden Sie Elemente, die bereits eine vid haben, niemals erneut hoch. Tickets laufen in ~1 h ab.
2. Sitzung: start_stdraft_session einmal pro Entwurf; session_id behalten. Vor jeder Bearbeitungsrunde check_stdraft_state(session_id, local_package_id) aufrufen:
   • brandneuer Entwurf: "" übergeben; server_package_id:"" erwarten → von Grund auf neu erstellen und mit base_package_id:"" pushen;
   • ansonsten der Baseline-Tabelle in official/web-collaborative-editing/SKILL.official.md folgen (veraltet → zuerst get_stdraft_snapshot).
3. Lokal erstellen mit den offiziellen atomaren Funktionen (Python ≥3.8, nur Stdlib, ausführen mit python -B, sys.path.insert(0, "C:/Users/<benutzer>/.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. Chain result["draft"]. Neue Entwurfswurzel: {"version":"0.1.0","segments":[{"id":"draft","type":"DRAFT","attributes":{"width":1920,"height":1080,"ratio_type":"16:9"}}]}.
   • Clip stumm schalten: apply_video(..., volume=0.0). Zeiten sind ganze ms.
   • SOURCE_RANGE_UNVERIFIED wird für jede vid/sid-Quelle ausgelöst – erwartet. Überprüfen Sie es selbst: source_start_ms + duration_ms × speed darf die Quellenlänge nicht überschreiten (aus upload_map.json oder duration_ms im Musiksuchergebnis).
   • Auswahl von Suchergebnissen: Bevorzugen Sie ein Element, dessen duration_ms die benötigte Länge abdeckt und dessen Titel/Beschriftung zur Stimmung passt; sagen Sie, welches Sie ausgewählt haben.
4. Push vorbereiten: python -B ~/.claude/skills/capcut/scripts/draft_tool.py slim draft.json draft_slim.json (kurze IDs, ein Segment pro Zeile, erneut validiert, warnt bei über ~60k Zeichen). Lesen Sie draft_slim.json und fügen Sie den vollständigen Text wörtlich als stdraft_json in push_stdraft_snapshot ein (dies kostet seine Größe zweimal an Token – halten Sie Entwürfe schlank).
5. Nach dem Push: Wenn das Ergebnis vom Harness in eine Datei gespeichert wurde, führen Sie draft_tool.py summary <datei> / urls <datei> aus; wenn es inline zurückkam, speichern Sie es zuerst in push_result.json (oder leiten Sie es: ... summary -). Geben Sie dem Benutzer web_editor_url als Markdown-Link, beschriftet mit web_editor_text wörtlich (serverlokalisiert, kann z.B. "Buksan sa CapCut" sein). Verwenden Sie das zurückgegebene stdraft_json/server_package_id als nächste Baseline.
   • Normale Serverumschreibungen (keine Fehler): vid:// → asset://<id>; DRAFT erhält eine zufällige ID und verliert ratio_type; Layer werden neu nummeriert; end.ms wird überall hinzugefügt; TEXT erhält font_color/line_max_width und ein PATCH-Kind ("style copy"); VIDEO erhält crop/background.*-Standards; AUDIO meta_type wird kleingeschrieben. Vergleichen Sie Inhalt, Timing, Lautstärke, Geschwindigkeit, Übergänge und Keyframes – nicht IDs oder Layernummern.
6. Optional embed_editor_url im integrierten Browser öffnen, um einen Blick zu werfen; es funktioniert nur, wenn dieser Browser im selben CapCut-Konto angemeldet ist. Große Projekte benötigen 30–60 s zum Laden; Text wird möglicherweise erst nach Auswahl eines Segments gezeichnet.

Push-Fallstricke (verifiziert)

• Timeout ≠ Fehler. Der erste Push in ein neues Konto kopiert jede Mediendatei und kann das Client-Timeout überschreiten, während er trotzdem erfolgreich ist. Niemals blind erneut pushen: zuerst check_stdraft_state; wenn jetzt eine Version existiert, get_stdraft_snapshot (via draft_tool zusammenfassen) und von dort fortfahren. Ein blinder erneuter Push gibt STDRAFT_VERSION_CONFLICT zurück.
• Ein Entwurf, der durch einen zeitlich überschrittenen Push erstellt wurde, wird möglicherweise nicht in der Bibliothek angezeigt und gibt keine URL zurück; ein weiterer Push darauf (gleicher Inhalt, korrekte Basis) gibt die Editor-URLs zurück.
• Größe: ~55k Zeichen zuverlässig gepusht; ~90k passten nicht in einen Aufruf. Halten Sie Pushe schlank (optionale Keyframes/Styles weglassen, im Web-Editor hinzufügen).

4. Verifizierte Fähigkeitsgrenzen

Funktioniert und überlebt Cloud-Speicherung: Videoclips (Quell-In-Point, Dauer, Lautstärke, Geschwindigkeit), Übergänge (hinzufügen/ersetzen/entfernen; gleicher Layer, zusammenhängend), Musik & Soundeffekte (sid:// aus Suche oder eigener vid://; Lautstärke; kein automatischer Loop), Filter mit Intensität, Klartext (Schriftart, Größe, Farbe, Position, Rahmen), Schrifttausch, Texteffekte (flower), Textvorlagen (Server fügt eine IN-Animation hinzu; Slot-Anzahl nicht verifizierbar), Untertitel mit Wort-Timing und update_caption_text, Entfernen/Aufheben, Platzierungs-/Layer-/Timing-Änderungen, scale_*/alpha-Keyframes auf Clips mit Geschwindigkeit 1.

Verloren oder defekt beim Speichern:

• VIDEO_EFFECT-Segmente (Videoeffekte und Gesichtseffekte) werden vollständig entfernt – sagen Sie dem Benutzer, Effekte im Web-Editor hinzuzufügen.
• Keyframes auf Clips, deren speed ≠ 1 ist, werden in der Zeit durch die Geschwindigkeit skaliert und meistens gelöscht.
• Alles, was der Builder nicht abdeckt (Masken, Sticker, Kurven, Grading), muss im Web-Editor erledigt werden.
• Export/Rendering ist nicht über das MCP verfügbar: Der Benutzer exportiert im CapCut-Editor.

Materialsichtung: music, sound_effect, video_effect berücksichtigen die Eingabeaufforderung; font, text_effect, text_template, face_effect, transition, filter geben eine feste kuratierte Liste (max. 20) unabhängig von der Eingabeaufforderung zurück – es gibt keinen einfachen Überblendungseffekt; kuratierte Schriftarten sind lateinisch (Chinesisch fällt auf die Standardschriftart vimo://7317175475195875841 zurück, die CJK rendert). Videomaterial/Bilder sind nicht durchsuchbar – laden Sie sie hoch.

Automatische Untertitel (auto_caption_submit / auto_caption_query): nur Spracherkennung; Pro-Mitgliedschaft erforderlich (kostenlose Konten erhalten PAYWALL_REQUIRED – benefit_check_label-Link wörtlich anzeigen). Nutzlos für Liedtexte (ein ganzes Lied gab eine einzelne Müllzeile zurück) – verwenden Sie stattdessen lokales Whisper + bekannte Texte für das Liedtext-Timing.

Vorlagensuche: capcut_template_search → capcut_template_search_poll_v2 abfragen bis zum Ende → templates_preview_v2(search_id) gibt die Vorlagendaten zurück (Karte nicht gerendert; Titel, Dauer, Verwendung und page_url für den Benutzer auflisten). Relevanz ist locker; Ergebnisse bleiben 15 Tage; max. 10.

KI-Rohschnitt (KI-Labor): capcut_ailab_start_edit(assets=[{resource_id: <vid>, file_name}], query) → abfragen → ein Plan-Ereignis trifft mit Status loop_turn_completed ein; den Plan an den Benutzer weiterleiten, dann capcut_ailab_submit_plan_response ohne card_id (die Ereignis-ID des Plans wird als plan_card_id_invalid abgelehnt) und mit dem genauen Auswahltext des Benutzers. Musik- und Final-Video-Ereignisse folgen (~2 min für einen 10 s-Schnitt). Rufen Sie video_preview mit dem context/resources des letzten Ereignisses unverändert auf, um das bearbeitbare STDraft (stdraft-Feld) des Ergebnisses zu erhalten – importieren Sie es in eine Entwurfssitzung, um die Bearbeitung fortzusetzen. Nur-Audio-Assets werden abgelehnt (unsupported_edit_file_name). Verwenden Sie das KI-Labor nicht für reine Untertitelanfragen.

Bild-/Videogenerierung (Seedream / Seedance): verbraucht Guthaben. Karten werden hier nicht gerendert, also: mit confirmed:false einreichen (kein unique_key) → bei CONFIRMATION_REQUIRED dem Benutzer den genauen credits_amount mitteilen → erst nachdem der Benutzer diesen Betrag im Chat ausdrücklich genehmigt hat, erneut mit confirmed:true und dem zurückgegebenen unique_key/derselben generate_id versuchen. Niemals im Namen des Benutzers bestätigen. capcut_generation_poll abfragen bis next_action=none, dann generation_result(task_id) für die finale(n) Mediendatei(en). Die Karte billing_confirmation ist nicht gerendert: Sie erhalten generation_result direkt, nachdem Sie auf CONFIRMATION_REQUIRED mit confirmed:true geantwortet haben.

5. Fehlerbehebung bei Fehlern

• get user workspace failed: check login error (jeder Aufruf) → abgelaufenes Grant → neu autorisieren (Abschnitt 0).
• ios_account_not_bind / auth failed → das CapCut-Konto hat nicht die erforderlichen Berechtigungen → bitten Sie den Benutzer, ein anderes Konto zu versuchen.
• STDRAFT_VERSION_CONFLICT → Entwurf läuft voraus → check_stdraft_state, get_stdraft_snapshot, integrieren, erneut pushen.
• AssetNotFound: code 0 / get mediainfo Fehler auf einer vid → das Material ist abgelaufen. Laden Sie die Quelldatei erneut hoch (sie erhält eine neue vid), aktualisieren Sie upload_map.json, referenzieren Sie die neue vid im Entwurf. Die vid eines Musik-Suchergebnisses ist stabil, solange der Entwurf gespeichert ist.
• session not exist: cus_* → die Sitzung ist zu alt (wird nach 5 min Inaktivität gelöscht). Erstellen Sie eine neue Sitzung (start_stdraft_session).
• BAD_REQUEST:AiLab.tv.TemplatePredictFailed beim KI-Rohschnitt → der Clip ist zu kurz (< 5 s) → bitten Sie den Benutzer um einen längeren Clip.
• Text wird im Web-Editor nicht gerendert → wählen Sie das Textsegment in der Zeitleiste aus; es wird nur beim Fokus gezeichnet.
• Bei automatischen Untertiteln: Kein Audiostream/Keine Sprache erkannt → das Audio enthält keine gesprochenen Wörter (z.B. Musik oder Soundeffekte).
• JSON-Fehler in Python-Ausführungen: Überprüfen Sie auf nicht standardkonforme Escape-Sequenzen und Byte-Reihenfolge-Marken.

6. Offizielle Dokumentation

• official/capcut-stdraft-builder/index.md – Hauptdokumentation
• official/capcut-stdraft-builder/reference/application.md – Funktionsverträge & Signaturen
• official/capcut-stdraft-builder/reference/STDraft_Protocol.md – Protokollspezifikation
• official/capcut-stdraft-builder/reference/validation.md – Validierungsregeln
• official/video-editing/references/post-editing.md – Nachbearbeitungs-Workflow
• official/video-editing/references/materials.md – Materialtypen & -eigenschaften
• official/video-editing/references/auto-captions.md – Automatische Untertitel
• official/video-editing/references/ai-rough-cut.md – KI-Rohschnitt
• official/web-collaborative-editing/SKILL.official.md – Kollaborative Bearbeitung (Sitzungen, Versionen)
• official/generate-media/SKILL.official.md – Bild-/Videogenerierung
• official/search-templates/SKILL.official.md – Vorlagensuche