Content
# 🎬 capcut-mcp
> Serveur **MCP** (Model Context Protocol) qui permet à un assistant IA comme
> **Claude** de **créer des montages vidéo CapCut** : assembler des clips,
> ajouter du texte/sous-titres, de la musique, des transitions, des effets… puis
> enregistrer le projet directement dans CapCut, prêt à exporter.
---
## 🧠 Comment ça marche (en clair)
CapCut **n'a pas d'API officielle** pour le piloter à distance. Mais l'application
range chaque projet sous forme d'un **« brouillon » (*draft*)** sur votre disque :
en réalité des fichiers texte au format JSON qui décrivent tout le montage
(quels clips, à quel moment, quels effets…).
Ce serveur écrit ces fichiers de brouillon **à votre place**, grâce à la
bibliothèque open-source [`pyJianYingDraft`](https://github.com/GuanYixuan/pyJianYingDraft)
(JianYing = la version d'origine de CapCut, même moteur).
```
Claude ──(commandes MCP)──► capcut-mcp ──► pyJianYingDraft ──► brouillon CapCut sur le disque
│
vous ouvrez CapCut ▼ et vous exportez
```
> 📌 **Important** : le serveur **crée et modifie un montage**, il ne fait PAS
> l'export final de la vidéo. L'export se fait dans CapCut, manuellement (CapCut
> ne permet pas d'exporter en ligne de commande). Le serveur s'exécute sur la
> **même machine** que CapCut (il a besoin d'accéder à vos fichiers).
---
## 📦 Installation
Nécessite **Python 3.10+** et l'application **CapCut Desktop** installée.
```bash
# 1. Récupérer le code
git clone https://github.com/pintoj71/capcut-mcp.git
cd capcut-mcp
# 2. Installer
pip install -e .
```
---
## 🔌 Brancher le serveur à Claude
### Claude Desktop / Claude Code
Ajoutez ceci à votre configuration MCP (`claude_desktop_config.json` pour
l'application de bureau, ou `.mcp.json` pour Claude Code) :
```json
{
"mcpServers": {
"capcut": {
"command": "capcut-mcp",
"env": {
"CAPCUT_DRAFT_FOLDER": "C:\\Users\\VOTRE_NOM\\AppData\\Local\\CapCut\\User Data\\Projects\\com.lveditor.draft"
}
}
}
}
```
> La variable `CAPCUT_DRAFT_FOLDER` indique où CapCut range ses brouillons.
> Si vous l'omettez, le serveur essaie de la deviner automatiquement (voir
> ci-dessous). Vous pouvez aussi la définir à chaud avec l'outil
> `set_draft_folder`.
**Emplacements habituels du dossier de brouillons :**
| Système | Chemin |
|---|---|
| **Windows** | `%LOCALAPPDATA%\CapCut\User Data\Projects\com.lveditor.draft` |
| **macOS** | `~/Movies/CapCut/User Data/Projects/com.lveditor.draft` |
---
## 🎯 De tes captures + photos à une vidéo Meta (le cas d'usage principal)
Pour publier sur **Instagram / Facebook (Reels, Stories, Feed)**, deux outils
font tout le gros du travail :
1. **`create_project(name, preset=...)`** — choisis un format Meta, la taille est
réglée pour toi :
| preset | taille | usage |
|---|---|---|
| `reels` / `story` / `vertical` | 1080×1920 | Reels & Stories (plein écran mobile) |
| `feed` / `portrait` | 1080×1350 | feed Instagram (recommandé) |
| `square` | 1080×1080 | carré |
| `landscape` | 1920×1080 | paysage 16:9 |
2. **`add_media_sequence([...])`** — donne la **liste de tes vidéos ET photos**
dans l'ordre voulu : elles sont posées bout à bout automatiquement (aucun
temps à calculer). Options : `transition` entre chaque média, `fit="blur"`
(fond flou pour caler une capture paysage dans un Reel vertical),
`ken_burns=True` (léger zoom sur les photos), `photo_duration`.
3. **`set_background_music(...)`** — ajoute la musique calée sur **toute la durée**
de la vidéo (rebouclée si trop courte), avec fondu de sortie.
### Exemple — demande en langage naturel à Claude
> « Crée un projet **Reels** nommé *chantier*. Enchaîne mes captures et photos
> du dossier : `intro.mp4`, `photo1.jpg`, `photo2.jpg`, `final.mp4`, avec un
> **fondu** entre chaque, **fond flou** et un **léger zoom** sur les photos.
> Mets le titre “INSTANT BY PINTO” en bas les 3 premières secondes. Ajoute la
> musique `fond.mp3` en fond discret. Enregistre. »
Claude enchaînera : `create_project(preset="reels")` →
`add_media_sequence([...], transition="叠化", fit="blur", ken_burns=True)` →
`add_text(...)` → `set_background_music(...)` → `save_project()`. Tu ouvres
CapCut, ton Reel est monté, prêt à exporter et publier sur Meta.
---
## 💬 Exemple d'utilisation avec Claude
Une fois branché, demandez simplement en langage naturel :
> « Crée un projet vertical 1080×1920 nommé *promo*. Mets le clip
> `C:\videos\intro.mp4` au début, puis `C:\videos\produit.mp4` à la suite avec
> une transition fondu. Ajoute le titre “PROMO -50%” en gros au centre les 3
> premières secondes, et la musique `C:\audio\fond.mp3` en fond à 30 % de
> volume. Enregistre. »
Claude enchaînera les outils : `create_project` → `add_video_clip` ×2 →
`add_text` → `add_audio` → `save_project`. Vous ouvrez ensuite CapCut, le projet
*promo* est là, prêt à exporter.
---
## 🧰 Outils disponibles
### Configuration & projets
| Outil | Rôle |
|---|---|
| `get_status` | État : dossier de brouillons, projet actif |
| `set_draft_folder` | Définir le dossier de brouillons CapCut |
| `create_project` | Créer un projet (preset Meta reels/feed/square… ou taille, fps) |
| `set_active_project` | Basculer sur un autre projet ouvert |
| `add_track` | Ajouter une piste (pour superposer/overlay) |
### Médias
| Outil | Rôle |
|---|---|
| ⭐ `add_media_sequence` | **Enchaîner automatiquement** une liste de vidéos + photos (transitions, fond flou, zoom) |
| ⭐ `set_background_music` | Musique de fond calée sur toute la durée (reboucle + fondu) |
| `add_video_clip` | Ajouter un clip vidéo précis (vitesse, volume, position, transition, anim, filtre, effet…) |
| `add_image` | Ajouter une image fixe (diaporama) |
| `add_audio` | Ajouter un audio / voix-off à un instant précis |
| `inspect_media` | Lire la durée / dimensions d'un fichier |
### Texte
| Outil | Rôle |
|---|---|
| `add_text` | Titre / légende (police, couleur, contour, fond, animation) |
| `add_subtitles_from_srt` | Importer un fichier de sous-titres `.srt` |
### Effets & filtres (pleine timeline)
| Outil | Rôle |
|---|---|
| `add_effect` | Effet visuel sur une plage de temps |
| `add_filter` | Filtre colorimétrique sur une plage de temps |
### Enregistrement & découverte
| Outil | Rôle |
|---|---|
| `save_project` | Écrire le brouillon sur le disque |
| `list_projects` | Lister les brouillons existants |
| `search_transitions` / `search_filters` / `search_video_effects` / `search_video_animations` / `search_text_animations` / `search_audio_effects` / `search_fonts` | Trouver les noms valides d'effets/transitions/polices |
> 🔎 Les noms d'effets/transitions de CapCut sont souvent en **chinois** (le
> moteur est chinois). Les outils `search_*` vous aident à retrouver le bon nom.
> `add_*` accepte aussi bien le nom chinois d'origine que le nom anglais quand il
> existe.
---
## ⏱️ Conventions
- **Tous les temps sont en secondes** (`start`, `duration`, `fade_in`…).
- **Couleurs** en hexadécimal : `#FFFFFF` (blanc), `#FF0000` (rouge)…
- **Position à l'écran** : `position_x` / `position_y` entre `-1` et `1`,
`0` = centré. `position_y = -0.8` ≈ bas de l'écran (sous-titres).
- **Pistes** : chaque type (vidéo, audio, texte…) a une piste principale créée
automatiquement. Pour **superposer** (un 2ᵉ clip par-dessus, un 2ᵉ texte…),
passez un `track` nommé ou créez-la avec `add_track`.
---
## ⚠️ Limites connues
- **Pas d'export automatique** : CapCut ne permet pas l'export en ligne de
commande ; on génère le projet, l'export reste manuel dans CapCut.
- **Format de brouillon ≈ version de CapCut** : `pyJianYingDraft` cible
certaines versions de CapCut/JianYing. Si un projet généré ne s'ouvre pas,
vérifiez la compatibilité de version de la bibliothèque.
- **Chemins de fichiers** : utilisez des **chemins absolus** vers vos médias ;
le serveur tourne sur la même machine que CapCut.
- Projet **non affilié** à CapCut / ByteDance. Usage personnel.
---
## 📄 Licence
MIT — voir [LICENSE](LICENSE).
S'appuie sur [`pyJianYingDraft`](https://github.com/GuanYixuan/pyJianYingDraft)
(le moteur de génération de brouillons) et le SDK
[`mcp`](https://github.com/modelcontextprotocol/python-sdk).
