# Arkeonix CapCut MCP

An MCP server for inspecting and editing CapCut Desktop draft projects through
local, version-safe timeline operations. It is designed for AI-assisted
documentary, social, and narration-first editing workflows.

The server edits draft files locally. It does not automate the CapCut UI or
upload media to a service.

## Features

- Read, clone, validate, save, and restore local CapCut drafts.
- Place and transform images, video, audio, subtitles, text, stickers, and
  timeline effects.
- Align ordered narration, visual, and subtitle clips from the real audio
  duration.
- Create keyframe motion, typography overlays, transitions, filters, masks,
  audio fades, and B-roll layers.
- Inspect timeline health before saving, with backups and protection against
  writing while CapCut is open.

## Requirements

- Node.js 18 or newer.
- FFmpeg and FFprobe available on `PATH`.
- CapCut Desktop.

On macOS, install FFmpeg with `brew install ffmpeg`. On Windows, use
`winget install Gyan.FFmpeg`.

## Install

```bash
git clone https://github.com/daviilpzDev/arkeonix-capcut-mcp.git
cd arkeonix-capcut-mcp
npm install
npm test
```

The optional setup script also checks prerequisites, installs dependencies,
syncs locally available application assets, and installs a clean draft
template:

```bash
./setup.sh
```

Downloaded application assets are intentionally ignored by Git. They can be
large and may be governed by separate vendor terms.

## Configuration

Use a local MCP entry such as:

```json
{
  "mcp": {
    "arkeonix-capcut": {
      "type": "local",
      "command": [
        "node",
        "/ABSOLUTE/PATH/TO/arkeonix-capcut-mcp/src/server.js"
      ],
      "enabled": true,
      "environment": {
        "CAPCUT_DRAFTS_DIR": "",
        "CAPCUT_TEMPLATE_DRAFT": ""
      }
    }
  }
}
```

`CAPCUT_DRAFTS_DIR` is optional when CapCut uses its standard location.
`CAPCUT_TEMPLATE_DRAFT` optionally names a draft used as the material template
when a target draft lacks a required media type.

The server also supports optional vision and B-roll integrations through
`GEMINI_API_KEY`, `OPENROUTER_API_KEY`, and `MAGNIFIC_API_KEY`. Keep these in
your local environment or MCP configuration, never in the repository.

## Safety Model

- Read the timeline and validate before making editorial changes.
- Clone a production draft before modifying it.
- Do not save while CapCut is running. The server refuses this by default.
- Saving writes a `.mcpbak` backup and validates the resulting draft.
- After saving, reload and inspect the draft to verify persistence.

## Editorial Workflow

For narration-first projects, make the narration duration the timing source.
Align ordered audio and subtitle clips, preserve every source duration, then
align visuals. For emphasis overlays, retain base subtitles but set them
invisible, place exact phrases at their spoken position, and use short,
non-overlapping word-reveal segments on a separate text track.

The included MCP tools use the `capcut_` prefix to make the target draft format explicit.

## Credits and License

Arkeonix CapCut MCP is a maintained distribution of the MIT-licensed
[`minminthaw/capcut-mcp`](https://github.com/minminthaw/capcut-mcp) project,
with Arkeonix workflow, reliability, and packaging changes. The original MIT
copyright notice is preserved in [LICENSE](LICENSE).