🎬 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

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

# 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:

{
  "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:

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

Cursor IDE

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

{
  "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

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

🎥 Media Import

📝 Text & Subtitles

🔊 Audio

✂️ Timeline Editing

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

# 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 and ensure ffprobe is on your PATH. Without it, the server uses default duration estimates.