# 🎬 CapCut MCP Server

An **MCP (Model Context Protocol) server** that gives AI assistants full control over CapCut video editing projects. Create projects, import media, add text/subtitles, manage audio, and edit timelines — all through AI-powered tools.

## How It Works

```text
AI Assistant  ──MCP Protocol──▶  CapCut MCP Server  ──Read/Write JSON──▶  CapCut Draft Files
                                  (Python/FastMCP)                          (draft_content.json)
```

CapCut stores every project as a folder with a `draft_content.json` file. This MCP server reads and writes those files directly. You edit via the AI, then open the project in CapCut to preview and export.

## Quick Start

### 1. Install

```bash
# Clone your repository
git clone https://github.com/baizo7/capcut_MCP_server-.git
cd capcut_MCP_server-

# Using pip
pip install -e ".[cli]"

# Or using uv (recommended)
uv pip install -e .
```

### 2. Configure your MCP client

#### Gemini IDE / Antigravity

On Windows, open your Gemini MCP configuration file located at:
`%USERPROFILE%\.gemini\config\mcp_config.json`

Add this to your `mcpServers` object:

```json
{
  "mcpServers": {
    "capcut": {
      "command": "python",
      "args": ["-m", "capcut_mcp.server"],
      "env": {
        "CAPCUT_DRAFTS_PATH": "C:\\Users\\LENOVO\\AppData\\Local\\CapCut\\User Data\\Projects\\com.lveditor.draft"
      }
    }
  }
}
```
*Note: After saving, restart the IDE for the new server to boot up.*

#### Claude Desktop

Add this to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "capcut": {
      "command": "python",
      "args": ["-m", "capcut_mcp.server"]
    }
  }
}
```

#### Cursor IDE

Add to `.cursor/mcp.json` in your project:

```json
{
  "mcpServers": {
    "capcut": {
      "command": "python",
      "args": ["-m", "capcut_mcp.server"]
    }
  }
}
```

### 3. Start editing!

Once configured, your AI assistant can use commands like:
- *"Create a new TikTok project called 'Summer Vibes'"*
- *"Import all videos from D:\footage\vacation and add them to the timeline"*
- *"Add subtitles: 'Hello!' at 0-2s and 'Welcome!' at 2-5s"*
- *"Trim the first clip to start at 3 seconds"*

---

## 🛑 Important Limitations & Workarounds

### 1. Windows Store Python Sandbox
If you are running the MCP server using Python installed from the **Microsoft Store** (which is common in Gemini IDE and Cursor), Windows automatically sandboxes writes to `AppData\Local`.
* **The Issue:** The AI will create projects perfectly, but Windows hides them from CapCut.
* **The Fix:** We built an automatic "Sandbox Escape" into the server using PowerShell! However, for best results, we highly recommend changing CapCut's default save location (Settings -> Project -> Save to) to your `Documents` folder, and updating your `CAPCUT_DRAFTS_PATH` environment variable to match it.

### 2. CapCut Does Not "Hot-Reload"
Because we are editing the raw JSON save files on your hard drive behind CapCut's back, CapCut does not instantly update its screen while you are actively editing a timeline.
* **To see changes:** You must click the "X" in CapCut to return to the Home screen, then click the project again to force CapCut to reload the timeline from the hard drive.
* **For new projects:** Simply switch tabs (e.g., from "Space" to "Home") to refresh the project list.

---

## Configuration

| Environment Variable | Description | Default |
|---|---|---|
| `CAPCUT_DRAFTS_PATH` | Path to your CapCut drafts folder | Auto-discovered |

### Auto-discovery

The server automatically checks these locations for CapCut projects:
- `%LOCALAPPDATA%\CapCut\User Data\Projects\com.lveditor.draft`
- `%LOCALAPPDATA%\CapCut\User Data\Drafts`

---

## Available Tools (25+)

### 📁 Project Management
| Tool | Description |
|---|---|
| `list_projects` | List all CapCut projects on this computer |
| `get_project_info` | Detailed project info: tracks, materials, segments |
| `create_project` | Create a new empty project (with canvas presets) |
| `duplicate_project` | Clone a project as a template |
| `delete_project` | Delete a project (requires confirmation) |
| `list_canvas_presets` | Show available canvas sizes (landscape, portrait, etc.) |

### 🎥 Media Import
| Tool | Description |
|---|---|
| `add_video` | Import a video file to the timeline |
| `add_image` | Add an image as a still clip |
| `add_media_batch` | Batch-import all media from a folder |
| `list_materials` | List all assets in a project |
| `remove_material` | Remove an asset and its timeline clips |

### 📝 Text & Subtitles
| Tool | Description |
|---|---|
| `add_text` | Add a text overlay at a specific time |
| `add_subtitles` | Bulk-add subtitles from a structured list |
| `update_text_style` | Change font, color, size, alignment |
| `update_text_content` | Change the text content |

### 🔊 Audio
| Tool | Description |
|---|---|
| `add_audio` | Add background music or sound effects |
| `set_volume` | Adjust volume of a specific clip |
| `mute_track` | Mute all clips on a track |
| `unmute_track` | Restore volume on a muted track |

### ✂️ Timeline Editing
| Tool | Description |
|---|---|
| `trim_clip` | Trim a clip's start/end point |
| `split_clip` | Split a clip into two parts at a timestamp |
| `move_clip` | Move a clip to a new timeline position |
| `delete_clip` | Remove a clip from the timeline |
| `reorder_clips` | Arrange clips sequentially with optional gaps |
| `set_clip_speed` | Change playback speed (slow-mo, fast-forward) |

---

## Safety Features

- **Automatic backups**: Every edit creates a `.backup` of the draft before modifying
- **Non-destructive**: Delete operations require explicit confirmation
- **Validation**: All file paths are verified before import

---

## Development

```bash
# Install in development mode
pip install -e ".[dev]"

# Run tests
python -m pytest tests/ -v

# Test with MCP Inspector (browser-based)
npx -y @modelcontextprotocol/inspector python -m capcut_mcp.server
```

---

## Important Notes

⚠️ **Unofficial**: This server reverse-engineers CapCut's project format. It is not affiliated with ByteDance.

⚠️ **Backups**: The server automatically backs up projects before modification, but always keep your own backups of important projects.

⚠️ **ffprobe**: For accurate video/audio duration detection, install [FFmpeg](https://ffmpeg.org/download.html) and ensure `ffprobe` is on your PATH. Without it, the server uses default duration estimates.