# CapCut MCP Server 🎬✨

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![MCP](https://img.shields.io/badge/MCP-2.2+-green.svg)](https://modelcontextprotocol.io)
[![CapCut](https://img.shields.io/badge/CapCut-Desktop%208.5+-black.svg)](https://www.capcut.com)

A Model Context Protocol (MCP) server for **CapCut Desktop**. Enables AI coding agents (Claude Code, Cursor, Windsurf, Antigravity) to programmatically assemble vertical videos, remove backgrounds via CapCut's native AI cutout, auto-duck background music, punch-zoom for retention, style viral karaoke captions, and lint social media safe zones directly on your local timeline.

JSON in, real CapCut draft out — open CapCut Desktop and your project is 100% assembled, layered, and ready for 1-click human review and export.

---

## Key Capabilities

### 1. 🪄 AI Background Removal (Smart Portrait Cutout)
- **Native CapCut Cutout (`flag: 3`)**: Programmatically sets the smart portrait matting flag on any video material in `draft_content.json`.
- **Temporal Consistency**: CapCut Desktop's local GRU video matting model (`tt_matting_video_gru`) automatically processes the subject when opened or exported — no flickering, transparent ghosting, or manual rotoscoping required.
- **Chroma Key**: Green/blue screen cutout with custom hex color, intensity, and shadow parameters.

### 2. 🎙️ Studio Audio Improver & Auto-Ducking
- **Fast DSP Mode (~1s)**:
  - High-pass filter (`80 Hz`) strips table thumps, traffic rumble, and HVAC infrasound.
  - FFT spectral de-hiss (`afftdn`) removes steady microphone hiss and fan noise.
  - Spoken clarity EQ (+2.5dB presence boost at 3.5kHz, -1.5dB muddiness cut at 250Hz).
  - Dynamic compression for level vocal consistency.
  - **`-14 LUFS` EBU R128 Normalization**: Broadcast/streaming standard for TikTok Shop, Instagram Reels, and YouTube Shorts.
- **Neural Isolation Mode (Demucs)**:
  - Uses deep neural stem separation (`htdemucs`) to isolate clean vocal stems from room echo, background chatter, and music bleed.
- **Smart Music Auto-Ducking**:
  - Injects `KFTypeVolume` keyframes to drop background music to **12%** during speech and swell it to **35%** during pauses and transitions.

### 3. 🔍 Retention Punch Zooms & Motion
- **Dynamic Attention Resets**: Automatically alternates between wide (`1.0x`) and punch-in (`1.15x`) keyframes (`UNIFORM_SCALE`) every 3–4 seconds to prevent viewer drop-off.

### 4. 🟡 Viral Karaoke Word-by-Word Highlight Captions
- **Hormozi / MrBeast Typography**: Takes word-level timestamps (Whisper, ElevenLabs) and highlights the active spoken word in `#FFD700` (yellow) or `#00FF66` (green) with a heavy black outline (`#000000FF`).

### 5. 🖼️ PiP Proof Overlays & Hook Headline Badges
- **Proof Overlays**: Injects Amazon 5-star reviews, scientific study screenshots, or TikTok comment bubbles into corners (`top_right`, `top_left`, `center_pop`) on Track 2 with smooth scaling and drop shadows.
- **Hook Badges**: High-contrast headline banners (e.g. "3 WARNING SIGNS", "DOCTOR REVEALS") pinned to top-center.

### 6. 🛡️ Social Media Safe Zone Linter & Fast Proxy Previews
- **Safe Zone QC (`capcut_lint_safe_zones`)**: Validates that text and overlays do not collide with TikTok / Instagram Reels UI elements (right-side like/comment icons, bottom username/sound banner).
- **Fast Proxy Renderer (`capcut_render_preview_proxy`)**: Stitches a lightweight 540x960 proxy MP4 in 2–4 seconds via FFmpeg for instant headless review.

### 7. 🌐 Multi-Language Cloner & Dubber
- **Instant EN $\to$ ES Localization**: Clones an existing draft, keeps all visual cuts, B-roll timing, and cutout settings, while swapping the audio track and regenerating translated captions.

---

## Tools Reference (17 Tools)

| Tool Name | Description |
|---|---|
| `capcut_improve_audio` | Enhances voiceover audio with noise reduction, clarity EQ, and `-14 LUFS` normalization (`mode: "fast"` or `"neural"`). |
| `capcut_create_draft` | Creates a new vertical 9:16 (1080x1920) or landscape CapCut project. |
| `capcut_add_video_clip` | Places video or avatar clips on the timeline with optional `smart_cutout=True`. |
| `capcut_set_background_removal` | Toggles CapCut's native portrait cutout (`smart_portrait`) or green screen (`chroma`) on any clip. |
| `capcut_add_audio_clip` | Adds voiceover, background music, or sound effects with custom volume. |
| `capcut_add_punch_zooms` | Injects `UNIFORM_SCALE` keyframes (e.g. 1.15x) every 3–4 seconds for retention. |
| `capcut_add_bg_music_with_ducking` | Adds background music with automatic `KFTypeVolume` ducking under speech. |
| `capcut_add_captions` | Renders sentence subtitles into CapCut bold text tracks. |
| `capcut_add_karaoke_captions` | Renders active word-by-word highlight karaoke subtitles (`#FFD700`). |
| `capcut_add_proof_overlay` | Adds Amazon review or comment screenshots at corners (`top_right`, `top_left`, etc.). |
| `capcut_add_hook_badge` | Pins headline warning pills and banners at top-center. |
| `capcut_lint_safe_zones` | Validates layout against TikTok and Reels UI margins and checks missing media. |
| `capcut_clone_and_revoice` | Clones draft visual composition and swaps audio/captions for localization. |
| `capcut_render_preview_proxy` | Builds a fast 540x960 proxy preview MP4 via FFmpeg in 2–4 seconds. |
| `capcut_assemble_ugc_video` | High-level convenience tool: enhances audio, places avatar, layers B-roll, styles captions, and outputs the draft. |
| `capcut_list_drafts` | Lists all existing CapCut projects on disk with duration. |
| `capcut_inspect_draft` | Inspects tracks, segments, durations, and materials of a draft. |

---

## Setup Instructions

### Prerequisites
- **Python 3.10+**
- **FFmpeg & FFprobe** on system `PATH`
- **CapCut Desktop** (Windows or macOS)

### Installation

```bash
git clone https://github.com/bchenner/capcut-mcp.git
cd capcut-mcp

# Install base dependencies
pip install -e .

# (Optional) Install neural voice isolation dependencies
pip install -e ".[neural]"
```

---

## Connecting to AI Agents

### 1. Claude Code
Add to your project's `.mcp.json`:

```json
{
  "mcpServers": {
    "capcut": {
      "command": "python",
      "args": ["-m", "capcut_mcp.server"],
      "env": {
        "PYTHONPATH": "/path/to/capcut-mcp/src"
      }
    }
  }
}
```

Or add globally via Claude Code CLI:
```bash
claude mcp add capcut -- python -m capcut_mcp.server
```

### 2. Cursor / Windsurf
Add to your `mcp.json` settings:
```json
{
  "mcpServers": {
    "capcut": {
      "command": "python",
      "args": ["-m", "capcut_mcp.server"],
      "env": {
        "PYTHONPATH": "C:/path/to/capcut-mcp/src"
      }
    }
  }
}
```

---

## Python API Example

```python
from capcut_mcp import CapCutDraft, improve_audio, render_draft_preview

# 1. Enhance speech audio
res = improve_audio("voiceover.wav", mode="fast", target_lufs=-14.0)

# 2. Build 9:16 vertical project
draft = CapCutDraft("Viral_Supplement_Ad", width=1080, height=1920, fps=30)

# 3. Add talking-head avatar with AI background removal
clip = draft.add_video_clip("avatar.mp4", start_ms=0, duration_ms=15000, smart_cutout=True, track_index=1)

# 4. Add dynamic punch zooms every 3.5s
draft.add_punch_zooms(clip["segment_id"], zoom_scale=1.15, interval_s=3.5)

# 5. Add B-roll background
draft.add_video_clip("broll.mp4", start_ms=0, duration_ms=15000, track_index=0)

# 6. Add background music with auto-ducking
music = draft.add_audio_clip("music.mp3", start_ms=0, duration_ms=15000, track_index=1)
draft.add_audio_ducking(
    music_segment_id=music["segment_id"],
    speech_intervals_ms=[{"start_ms": 1000, "end_ms": 6000}, {"start_ms": 7000, "end_ms": 14000}],
    duck_volume=0.12,
    normal_volume=0.35
)

# 7. Add PiP Amazon 5-star review proof overlay
draft.add_proof_overlay("amazon_5star.png", start_ms=3000, duration_ms=4000, position="top_right")

# 8. Add top hook warning badge
draft.add_hook_badge("WARNING: HIGH CORTISOL", start_ms=0, duration_ms=3500)

# 9. Lint for TikTok UI safe zones
report = draft.lint_draft(platform="tiktok")
print("Safe zone check:", report["passed"])

# 10. Save to CapCut Desktop
draft.save()
print("Draft ready in CapCut Desktop!")
```

---

## Testing

Run the comprehensive test suite verifying FFmpeg audio mastering, draft generation, motion keyframes, auto-ducking, karaoke captions, safe-zone linter, and proxy rendering:

```bash
python tests/test_mcp.py
```

---

## License

MIT License © 2026 [bchenner](https://github.com/bchenner)