capcut-mcp

MCP server that creates and edits CapCut desktop drafts locally. CapCut has no public API, so this server writes the project files CapCut reads from disk (draft_content.json + draft_meta_info.json). You build the timeline through MCP tools and then open the project in CapCut desktop to preview and export.

Tools

Tool	Description
create_draft	Creates an empty draft (default canvas 1080x1920 @ 30fps)
list_drafts	Lists drafts in the drafts folder
get_draft	Returns the timeline: tracks, segments, timings
add_video	Adds a video clip (duration/dimensions detected via ffprobe)
add_image	Adds a still image (default 5s on screen)
add_audio	Adds music or voiceover to an audio track
add_text	Adds a text overlay with color, size and position

Placement rules: segments append to the end of their track by default (atSeconds overrides). If a segment overlaps an existing one, a new track is created automatically, so overlays "just work".

Setup

pnpm install
pnpm build

Register in Claude Code:

claude mcp add --scope user capcut -- node /absolute/path/to/capcut-mcp/dist/index.js

Configuration

Env var	Default	Purpose
CAPCUT_DRAFT_ROOT	~/Movies/CapCut/User Data/Projects/com.lveditor.draft	Where drafts are read/written (CapCut's folder on macOS)

Installing ffmpeg (brew install ffmpeg) is recommended: ffprobe detects media duration and dimensions automatically. Without it, image dimensions fall back to macOS sips, and video/audio clips require an explicit durationSeconds.

Architecture

Layered, dependency-injected design. CompositionRoot is the only place where concrete classes are instantiated; every collaborator is injected through constructor interfaces (ports & adapters).

classDiagram
    class DraftToolController {
        +registerOn(server)
    }
    class DraftService {
        +createDraft()
        +addVideo() / addImage() / addAudio() / addText()
        +listDrafts() / getDraft()
    }
    class DraftDocument {
        +insertSegment()
        +addMaterial()
        +summary()
    }
    class DraftRepository {
        <<interface>>
    }
    class MediaProbe {
        <<interface>>
    }
    class FileChecker {
        <<interface>>
    }
    class FsDraftRepository
    class ChainMediaProbe
    class FfprobeMediaProbe
    class SipsImageProbe
    class MaterialFactory
    class SegmentFactory
    class DraftContentFactory

    DraftToolController --> DraftService
    DraftService --> DraftRepository
    DraftService --> MediaProbe
    DraftService --> FileChecker
    DraftService --> MaterialFactory
    DraftService --> SegmentFactory
    DraftService --> DraftContentFactory
    DraftRepository <|.. FsDraftRepository
    MediaProbe <|.. ChainMediaProbe
    ChainMediaProbe o--> FfprobeMediaProbe
    ChainMediaProbe o--> SipsImageProbe
    FsDraftRepository --> DraftDocument

Patterns in play:

• Facade — DraftService exposes one use case per tool and owns the workflow.
• Repository — FsDraftRepository isolates all disk I/O and the meta-info bookkeeping.
• Factory — DraftContentFactory / MaterialFactory / SegmentFactory encapsulate CapCut's JSON blocks.
• Strategy + Chain of Responsibility — MediaProbe implementations try ffprobe first, then sips.
• Dependency Injection — constructor injection everywhere; IdGenerator and Clock are injected too, which keeps every unit test deterministic (see src/testing/fakes.ts).

DraftDocument wraps the raw draft JSON and only mutates the parts it understands, preserving any field CapCut adds on its own.

Validation

Verified end to end against CapCut desktop 3.3.0 (macOS): generated drafts show up in CapCut's project list with the right duration, open in the editor, and the full timeline loads — video, photo, audio (with volume) and text overlays with their exact timings. CapCut's own autosave round-trips the generated structure without dropping anything.

Limitations

• Media must live on a stable user path (e.g. under ~/Movies or ~/Documents). CapCut marks files under /tmp as "not accessible" and asks to relink them.
• No effects, transitions, keyframes or exports yet — CapCut itself does the rendering/export.
• Drafts heavily edited inside CapCut can contain features this server does not model; it will preserve them on load/save, but it only manipulates video/image/audio/text segments.

Development

pnpm test        # vitest unit tests
pnpm typecheck
pnpm dev         # run from sources (tsx)