skill-capcut-claude

CapCut depuis Claude

Le MCP CapCut a été construit pour Codex. Cette compétence est l'adaptation pour Claude : le matériel officiel est conservé textuellement sous official/ (plugin v0.2.6), et ce fichier indique comment l'utiliser ici, ainsi que ce qui a été vérifié en utilisation réelle (2026-10-26/27, onglet Code de Claude Desktop, Windows).

Les chemins ci-dessous sont relatifs au dossier de cette compétence (~/.claude/skills/capcut/).

Si official/ est manquant (clone frais), exécutez d'abord python scripts/fetch_official.py – il télécharge le bundle du plugin CapCut depuis le CDN de CapCut (le matériel officiel n'est pas redistribué dans ce dépôt). --force le rafraîchit à la dernière version publiée.

0. Connexion (à faire en premier si les outils sont manquants ou défaillants)

La seule façon qui fonctionne de se connecter est les serveurs MCP locaux dans la configuration de Claude Desktop, via mcp-remote. Ajouter CapCut en tant que connecteur personnalisé sur claude.ai ne fonctionne PAS : le serveur OAuth de CapCut rejette l'enregistrement dynamique du client de Claude ("无法在 CapCut 的登录服务中注册"), et un identifiant client ne peut pas être fourni.

%LOCALAPPDATA%\Claude-Data\<profile>\claude_desktop_config.json (ou %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 = outils liés au compte (OAuth). capcut_resource = outils de carte sans identité (pas de connexion). Sauvegardez la configuration avant de la modifier ; l'utilisateur doit quitter complètement et rouvrir Claude après modification.

Configuration à partir de zéro (pas d'outils mcp__capcut__* dans la session) :

1. Vérifiez les prérequis : node --version (≥14) et npx dans le PATH.
2. Trouvez la configuration en direct : recherchez d'abord %LOCALAPPDATA%\Claude-Data\*\claude_desktop_config.json, puis %APPDATA%\Claude\claude_desktop_config.json. Lisez-la, copiez-la dans claude_desktop_config.json.bak-<date>, ajoutez les deux entrées sous mcpServers (créez la clé si absente) sans toucher à rien d'autre, et ré-analysez le fichier en tant que JSON pour confirmer qu'il est valide.
3. Demandez à l'utilisateur de se connecter au navigateur système par défaut avec le compte CapCut dans lequel les brouillons doivent être enregistrés, puis quittez complètement Claude (icône de la barre d'état système → Quitter) et rouvrez-le.
4. Au démarrage, mcp-remote ouvre la page d'autorisation CapCut dans ce navigateur ; l'utilisateur approuve (un flash et une fermeture instantanés signifie qu'il s'est auto-approuvé – c'est bon).
5. La session en cours ne peut pas voir les serveurs ajoutés après son démarrage : continuez dans une nouvelle session de l'onglet Code. Vérifiez-y avec start_stdraft_session (devrait renvoyer un session_id) et search_capcut_material (type: music).
6. Optionnel : connectez le navigateur intégré de Claude au même compte CapCut afin que les brouillons puissent y être inspectés.

• Les jetons OAuth sont mis en cache dans ~/.mcp-auth/mcp-remote-v1/<hash>_tokens.json et <hash>_client_info.json.
• Réautoriser / changer de compte : demandez d'abord à l'utilisateur ; supprimez ces deux fichiers ; l'utilisateur se connecte au navigateur système par défaut avec le compte CapCut souhaité (même méthode de connexion – Google/e-mail/TikTok sont des comptes différents) avant de redémarrer ; puis quittez complètement et rouvrez Claude ; mcp-remote ouvre la page d'autorisation CapCut (elle peut flasher et se fermer si ce navigateur est déjà connecté – c'est un succès). Vérifiez avec start_stdraft_session.
• Symptôme get user workspace failed: check login error à chaque appel = l'autorisation en cache est morte → réautorisez comme ci-dessus.
• La réautorisation déconnecte le même compte des autres sessions Web CapCut (y compris le navigateur intégré de Claude) ; l'utilisateur doit s'y reconnecter.
• Les brouillons sont enregistrés dans le compte sous lequel le MCP est autorisé. Si l'utilisateur ne peut pas voir un brouillon, comparez d'abord les comptes.

1. Quelle interface fonctionne

Interface	Statut
Session de l'onglet Code de Claude Desktop	Tout ce qui suit fonctionne. Utilisez-la pour le travail CapCut.
Téléphone contrôlant à distance une session de l'onglet Code	Identique à l'onglet Code (les outils s'exécutent sur le PC).
Chat Desktop / chat téléphonique accédant aux outils du PC	Les outils de brouillon échouent avec "session_id manquant" (le pont semble laisser tomber un paramètre littéralement nommé session_id) ; les cartes peuvent ne pas s'afficher. Ne faites pas d'édition de brouillon là-bas.
Chat téléphonique seul	Pas de CapCut du tout (les serveurs sont locaux sur le PC).

Les cartes (capcut_resource : templates_preview_v2, editing_plan, video_preview, background_music, billing_confirmation) sont récupérées mais pas rendues dans l'onglet Code – les résultats arrivent sous forme de texte/JSON. N'attendez jamais une carte ; lisez les données et présentez-les vous-même.

2. Documentation officielle à lire (uniquement ce dont la tâche a besoin)

Incontournable pour tout travail sur les brouillons : official/capcut-stdraft-builder/reference/application.md (contrats des fonctions). Tout le reste uniquement lorsque la tâche le touche.

Tâche	Lire
Transfert de montage brut ou sous-titres sur une vidéo existante	official/video-editing/references/post-editing.md
Session/version/push/conflits	official/web-collaborative-editing/SKILL.official.md (+ references/conflict-recovery.md)
Questions sur le protocole au niveau des champs	official/capcut-stdraft-builder/reference/STDraft_Protocol.md, validation.md
Matériels	official/video-editing/references/materials.md
Sous-titres	official/video-editing/references/auto-captions.md
Montage rapide IA	official/video-editing/references/ai-rough-cut.md
Génération d'image/vidéo	official/generate-media/SKILL.official.md + references/
Recherche de modèles	official/search-templates/SKILL.official.md

Ignorer les parties propres à Codex : installation/mise à niveau du plugin codex, codex app-server/OAuth capcut-login.mjs, "New-Task Handoff"/fork, require_escalated indicateurs de bac à sable, saisie de ticket TTY, "terminer le tour en silence après une carte".

3. Flux de travail principal : créer/modifier un brouillon cloud

Shell : exécutez les commandes dans l'outil Bash (Git Bash), pas PowerShell. Utilisez des chemins Windows avec des barres obliques (D:/proj/clip.mp4) ou entre guillemets simples. Travaillez dans le dossier du projet de l'utilisateur (par exemple <project>/capcut_work/) afin que les cartographies de téléchargement et les brouillons survivent à la session.

1. Téléchargez les médias locaux uniquement avec le téléchargeur officiel (jamais de code VOD fait maison) :
   • capcut_asset_upload_credential avec version: 2 et files: [{file_name, size_bytes}] pour l'ensemble du lot → upload_ticket (une capacité de lot unique de courte durée ; elle passe nécessairement par cette conversation une fois – ne la consignez jamais ailleurs).
   • Écrivez le ticket sans problèmes de saut de ligne final, transmettez-le via stdin (jamais dans argv), supprimez le fichier :

     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
     

     (fichier unique : --file <chemin> --client-id c1 ; progression → stderr, JSON → stdout.)
   • Succès = vid non vide et setPublic.success:true. Sauvegardez une carte nom → {vid, duration} (upload_map.json) ; ne retéléchargez jamais les éléments qui ont déjà un vid. Les tickets expirent dans environ 1 heure.
2. Session : start_stdraft_session une fois par brouillon ; conservez session_id. Avant chaque cycle d'édition, appelez check_stdraft_state(session_id, local_package_id) :
   • brouillon tout nouveau : passez "" ; attendez server_package_id:"" → construisez à partir de zéro et poussez avec base_package_id:"" ;
   • sinon, suivez le tableau de base dans official/web-collaborative-editing/SKILL.official.md (obsolète → get_stdraft_snapshot d'abord).
3. Construisez localement avec les fonctions atomiques officielles (Python ≥3.8, stdlib uniquement, exécutez avec python -B, sys.path.insert(0, "C:/Users/<utilisateur>/.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. Chaînez result["draft"]. Nouvelle racine de brouillon : {"version":"0.1.0","segments":[{"id":"draft","type":"DRAFT","attributes":{"width":1920,"height":1080,"ratio_type":"16:9"}}]}.
   • Mettez un clip en sourdine : apply_video(..., volume=0.0). Les temps sont en ms entières.
   • SOURCE_RANGE_UNVERIFIED est levé pour chaque source vid/sid – attendu. Vérifiez-le vous-même : source_start_ms + duration_ms × speed ne doit pas dépasser la longueur de la source (depuis upload_map.json, ou duration_ms dans le résultat de la recherche musicale).
   • Choix des résultats de recherche : préférez un élément dont duration_ms couvre la longueur nécessaire et dont le titre/légende correspond à l'ambiance ; dites lequel vous avez choisi.
4. Préparez le push : python -B ~/.claude/skills/capcut/scripts/draft_tool.py slim draft.json draft_slim.json (identifiants courts, un segment par ligne, re-validé, avertit au-delà d'environ 60 000 caractères). Lisez draft_slim.json et collez son texte intégral textuellement comme stdraft_json dans push_stdraft_snapshot (cela coûte deux fois sa taille en jetons – gardez les brouillons légers).
5. Après le push : si le résultat a été enregistré dans un fichier par le harnais, exécutez draft_tool.py summary <fichier> / urls <fichier> ; s'il est revenu en ligne, sauvegardez-le d'abord dans push_result.json (ou pipez-le : ... summary -). Donnez à l'utilisateur web_editor_url sous forme de lien Markdown étiqueté avec web_editor_text textuellement (localisé sur le serveur, peut être par exemple "Buksan sa CapCut"). Utilisez le stdraft_json/server_package_id retourné comme prochaine base.
   • Réécritures normales du serveur (pas des erreurs) : vid:// → asset://<id> ; DRAFT reçoit un identifiant aléatoire et perd ratio_type ; les couches sont renumérotées ; end.ms est ajouté partout ; TEXT obtient font_color/line_max_width et un enfant PATCH ("copie de style") ; VIDEO obtient les valeurs par défaut crop/background.* ; AUDIO meta_type devient minuscules. Comparez le contenu, le timing, le volume, la vitesse, les transitions et les images clés – pas les identifiants ou les numéros de couche.
6. Ouvrez éventuellement embed_editor_url dans le navigateur intégré pour vérifier ; cela ne fonctionne que si ce navigateur est connecté au même compte CapCut. Les grands projets mettent 30 à 60 secondes à se charger ; le texte peut ne s'afficher qu'après la sélection d'un segment.

Pièges du push (vérifiés)

• Le délai d'attente n'est pas un échec. Le premier push sur un nouveau compte copie chaque fichier multimédia et peut dépasser le délai d'attente du client tout en réussissant. Ne repoussez jamais aveuglément : check_stdraft_state d'abord ; si une version existe maintenant, get_stdraft_snapshot (résumez via draft_tool) et continuez à partir de là. Un repoussage aveugle renvoie STDRAFT_VERSION_CONFLICT.
• Un brouillon créé par un push qui a expiré peut ne pas apparaître dans la Bibliothèque et ne renvoie aucune URL ; un push supplémentaire par-dessus (même contenu, base correcte) renvoie les URL de l'éditeur.
• Taille : environ 55 000 caractères poussés de manière fiable ; environ 90 000 ne tiennent pas dans un seul appel. Gardez les push légers (supprimez les images clés/styles optionnels, ajoutez-les dans l'éditeur web).

4. Limites de capacité vérifiées

Fonctionne et survit à la sauvegarde cloud : clips vidéo (point d'entrée source, durée, volume, vitesse), transitions (ajouter/remplacer/supprimer ; même couche, contiguës), musique et effets sonores (sid:// de la recherche ou propre vid:// ; volume ; pas de boucle automatique), filtres avec intensité, texte brut (police, taille, couleur, position, bordure), changement de police, effets de texte (flower), modèles de texte (le serveur ajoute une animation IN ; nombre d'emplacements non vérifiable), sous-titres avec minutage des mots et update_caption_text, supprimer/définir, changements de placement/couche/timing, images clés scale_*/alpha sur les clips avec vitesse 1.

Perdu ou cassé lors de la sauvegarde :

• Les segments VIDEO_EFFECT (effets vidéo et effets de visage) sont entièrement supprimés – dites à l'utilisateur d'ajouter des effets dans l'éditeur web.
• Les images clés sur les clips dont speed ≠ 1 voient leurs temps mis à l'échelle par la vitesse et sont pour la plupart supprimées.
• Tout ce que le générateur ne couvre pas (masques, autocollants, courbes, étalonnage) doit être fait dans l'éditeur web.
• L'exportation/le rendu n'est pas disponible via le MCP : l'utilisateur exporte dans l'éditeur CapCut.

Recherche de matériels : music, sound_effect, video_effect honorent la requête ; font, text_effect, text_template, face_effect, transition, filter renvoient une liste organisée fixe (max 20) quelle que soit la requête – il n'y a pas de fondu enchaîné simple ; les polices organisées sont latines (le chinois revient à la police par défaut vimo://7317175475195875841, qui rend le CJK). Les séquences vidéo/images ne sont pas recherchables – téléchargez-les.

Sous-titres automatiques (auto_caption_submit / auto_caption_query) : reconnaissance vocale uniquement ; abonnement Pro nécessaire (les comptes gratuits obtiennent PAYWALL_REQUIRED – affichez le lien benefit_check_label textuellement). Inutile pour les paroles de chansons (une chanson entière renvoie une ligne de déchets) – utilisez Whispers local + paroles connues pour le minutage des paroles à la place.

Recherche de modèles : capcut_template_search → interrogez capcut_template_search_poll_v2 jusqu'à être terminal → templates_preview_v2(search_id) renvoie les données du modèle (carte non rendue ; liste du titre, de la durée, de l'utilisation et de page_url pour l'utilisateur). La pertinence est lâche ; les résultats persistent 15 jours ; max 10.

Montage rapide IA (AI Lab) : capcut_ailab_start_edit(assets=[{resource_id: <vid>, file_name}], query) → interrogez → un événement de plan arrive avec le statut loop_turn_completed ; relayez le plan à l'utilisateur, puis capcut_ailab_submit_plan_response sans card_id (l'identifiant d'événement du plan est rejeté comme plan_card_id_invalid) et avec le texte exact du choix de l'utilisateur. Les événements musicaux et vidéo finaux suivent (~2 min pour un montage de 10 s). Appelez video_preview avec le context/resources de l'événement final inchangés pour obtenir le STDraft modifiable du résultat (champ stdraft) – importez-le dans une session de brouillon pour continuer l'édition. Les ressources audio uniquement sont rejetées (unsupported_edit_file_name). N'utilisez pas l'AI Lab pour les demandes de sous-titres uniquement.

Génération d'image/vidéo (Seedream / Seedance) : dépense des crédits. Les cartes ne se rendent pas ici, donc : soumettez avec confirmed:false (pas de unique_key) → en cas de CONFIRMATION_REQUIRED dites à l'utilisateur le credits_amount exact → seulement après que l'utilisateur a explicitement approuvé ce montant dans le chat, réessayez avec confirmed:true et le unique_key/même generate_id renvoyé. Ne confirmez jamais au nom de l'utilisateur. Interrogez capcut_generation_poll jusqu'à ce que next_action=none, puis generation_result(task_i…) (tronqué).