Skip to main content
Glama

capcut-mcp-server

GitHub repo License: MIT

A local MCP (Model Context Protocol) server that lets Claude drive CapCut/Jianying video editing — create a draft, add text/video/audio/image tracks, subtitles, effects, stickers, and keyframe animations, then save a draft file CapCut can open.

How this actually works (read this first)

CapCut has no public API. This server does not talk to the CapCut app directly. It's a thin wrapper around the local HTTP backend from the open-source VectCutAPI project, which generates CapCut/Jianying draft files that you then copy into CapCut's drafts folder.

That means there are two things running for this to work:

Claude  <--stdio-->  capcut-mcp-server (this project)  <--HTTP-->  VectCutAPI's capcut_server.py

You must set up and run VectCutAPI's Python backend yourself — this project does not include or install it.

Related MCP server: capcut-mcp

1. Set up the VectCutAPI backend (prerequisite)

git clone https://github.com/sun-guannan/VectCutAPI.git
cd VectCutAPI
python -m venv venv-capcut
source venv-capcut/bin/activate      # Windows: venv-capcut\Scripts\activate
pip install -r requirements.txt
cp config.json.example config.json   # edit if needed

python capcut_server.py              # starts the HTTP API on http://127.0.0.1:9001

Leave this running in its own terminal. Requirements: Python 3.10+, FFmpeg, and CapCut or Jianying installed (international CapCut works; the desktop app itself is only needed to open the drafts this produces, not to generate them).

2. Build this server

npm install
npm run build

This produces dist/index.js, the stdio entry point.

3. Point it at your VectCutAPI backend

By default the server calls http://127.0.0.1:9001. Override with an env var if you changed the port:

CAPCUT_API_URL=http://127.0.0.1:9001

4. Wire it into a client

This is a local stdio server, not a remote connector — it runs as a subprocess of whatever client launches it, so it's added differently depending on where you want to use it:

Claude Desktop

Edit your claude_desktop_config.json (Settings → Developer → Edit Config) and add:

{
  "mcpServers": {
    "capcut": {
      "command": "node",
      "args": ["/absolute/path/to/capcut-mcp-server/dist/index.js"],
      "env": { "CAPCUT_API_URL": "http://127.0.0.1:9001" }
    }
  }
}

Restart Claude Desktop afterward.

Claude Code

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

Cowork

Cowork's "Add custom connector" flow (Settings → Customize → Connectors) expects a remote MCP server URL reachable from Anthropic's cloud — it can't launch a local stdio subprocess on your machine. To use this server from Cowork you'd need to deploy it (and the VectCutAPI backend) somewhere with a public HTTPS endpoint and switch this server's transport to streamable HTTP. For local-only use, Claude Desktop or Claude Code (above) are the supported paths.

Available tools

Tool

What it does

capcut_create_draft

Create a new draft (project). Call this first.

capcut_add_text

Add a text/title/caption element, with shadow, background panel, multi-style segments.

capcut_add_video

Add a video clip to the timeline.

capcut_add_audio

Add an audio clip (music, voiceover, SFX).

capcut_add_image

Add a static image asset.

capcut_add_subtitle

Import an SRT subtitle file.

capcut_add_effect

Apply a visual effect/filter over a time range.

capcut_add_sticker

Place a sticker asset.

capcut_add_video_keyframe

Add property keyframes (scale/position/rotation/alpha) for animation.

capcut_save_draft

Save/finalize the draft. Call this last.

Every add_* tool accepts an extra_params object as an escape hatch for any VectCutAPI field not modeled explicitly in the typed schema — the underlying API has more optional fields (nested transform/animation objects, etc.) than are fully documented, so extra_params is merged directly into the request body.

Typical workflow

  1. capcut_create_draft → get draft_id

  2. One or more capcut_add_video / capcut_add_image / capcut_add_audio / capcut_add_text / capcut_add_subtitle / capcut_add_effect / capcut_add_sticker / capcut_add_video_keyframe calls against that draft_id

  3. capcut_save_draft → generates a dfd_* folder next to capcut_server.py

  4. Copy that folder into your CapCut/Jianying drafts directory to open it in the app

Troubleshooting

  • "Could not reach the CapCut API backend" — capcut_server.py isn't running, or is running on a different port than CAPCUT_API_URL points to.

  • CapCut doesn't show the draft — make sure you copied the generated dfd_* folder into CapCut's actual drafts directory (not just left it next to capcut_server.py).

  • A field you need isn't in the schema — pass it via extra_params; check VectCutAPI's example.py for the exact field name the backend expects.

Development

npm run dev     # tsx watch — rebuild/rerun on save
npm run build   # tsc compile to dist/
npm run clean   # remove dist/

Available Tools

10 tools
capcut_add_audioAdd Audio Track to CapCut DraftA

Add an audio clip (music, voiceover, sound effect) to an existing draft's timeline.

Args:

  • draft_id (string, required): From capcut_create_draft.

  • audio_url (string, required): URL or local path of the source audio.

  • start (number, seconds): Placement on the timeline. end is optional (defaults to full clip length).

  • volume (number): Playback volume multiplier, 1.0 = original.

  • speed (number): Playback speed multiplier, 1.0 = original.

  • effects (string[]): Named audio effects, e.g. ['echo', 'denoise'].

  • extra_params: Any additional VectCutAPI field not modeled above.

Returns: JSON confirming the audio clip was added to the timeline.

Inputs: draft_id (required), audio_url (required), end, speed, +4 more.

capcut_add_effectAdd Visual Effect to CapCut DraftB

Apply a visual effect or filter to an existing draft over a given time range.

Args:

  • draft_id (string, required): From capcut_create_draft.

  • effect_type (string, required): Effect/filter identifier.

  • start (number, seconds), end or duration: Time range the effect is active.

  • params (number[]): Effect-specific numeric parameters, in the order VectCutAPI's effect definition expects (varies by effect_type); use null for an item to fall back to its default.

  • extra_params: Any additional VectCutAPI field not modeled above.

Returns: JSON confirming the effect was added.

Inputs: draft_id (required), effect_type (required), end, start, +3 more.

capcut_add_imageAdd Image Asset to CapCut DraftB

Add a static image (photo, graphic, generated art) to an existing draft's timeline.

Args:

  • draft_id (string, required): From capcut_create_draft.

  • image_url (string, required): URL or local path of the source image.

  • start/end (number, seconds): Placement on the timeline.

  • transform_x/transform_y, scale_x/scale_y: Position and scale.

  • animation (string): Named entrance/loop animation, e.g. 'zoom_in'.

  • transition (string): Named transition, e.g. 'fade_in'.

  • extra_params: Any additional VectCutAPI field not modeled above.

Returns: JSON confirming the image asset was added to the timeline.

Inputs: end (required), draft_id (required), image_url (required), start, +7 more.

capcut_add_stickerAdd Sticker to CapCut DraftA

Place a sticker asset on an existing draft's timeline.

Args:

  • draft_id (string, required): From capcut_create_draft.

  • resource_id (string, required): ID of the sticker resource.

  • start (number, seconds), end (optional): Time range the sticker is visible.

  • position_x/position_y, scale, rotation: Placement and transform.

  • extra_params: Any additional VectCutAPI field not modeled above.

Returns: JSON confirming the sticker was added.

Inputs: draft_id (required), resource_id (required), end, scale, +5 more.

capcut_add_subtitleAdd SRT Subtitles to CapCut DraftA

Import an SRT subtitle file into an existing draft, applying consistent styling and timing.

Args:

  • draft_id (string, required): From capcut_create_draft.

  • srt_path (string, required): Path or URL to the .srt file.

  • font_style (string): Named font style preset.

  • position (string): Named position preset, e.g. 'bottom_center'.

  • extra_params: Any additional VectCutAPI field not modeled above.

Returns: JSON confirming the subtitle track was added.

Don't use when: you only need a single one-off text overlay — use capcut_add_text instead.

Inputs: draft_id (required), srt_path (required), position, font_style, +1 more.

capcut_add_textAdd Text to CapCut DraftA

Add a text element (title, caption, lower-third, etc.) to an existing draft's timeline.

Args:

  • draft_id (string, required): From capcut_create_draft.

  • text (string, required): The text content.

  • start/end (number, seconds): Time range the text is visible.

  • font, font_size, font_color: Basic styling.

  • shadow_enabled/shadow_color/shadow_alpha: Drop shadow.

  • background_color/background_alpha/background_round_radius: Background panel behind the text.

  • text_styles: Array of {start, end, font_color} for multi-color segments within the same text block.

  • extra_params: Any additional VectCutAPI field not modeled above.

Returns: JSON confirming the text element was added, including which optional features were used.

Don't use when: you need burned-in subtitles from an SRT file — use capcut_add_subtitle instead.

Inputs: end (required), text (required), draft_id (required), font, +13 more.

capcut_add_videoAdd Video Track to CapCut DraftA

Add a video clip to an existing draft's timeline (e.g. as background footage or B-roll).

Args:

  • draft_id (string, required): From capcut_create_draft.

  • video_url (string, required): URL or local path (as supported by the backend) of the source video.

  • start/end (number, seconds): Placement on the timeline.

  • volume (number): Playback volume multiplier, 1.0 = original.

  • transition (string): Named transition, e.g. 'fade_in'.

  • transform_x/transform_y, scale_x/scale_y: Position and scale.

  • extra_params: Any additional VectCutAPI field not modeled above.

Returns: JSON confirming the video clip was added to the timeline.

Inputs: end (required), draft_id (required), video_url (required), start, +7 more.

capcut_add_video_keyframeAdd Keyframe Animation to CapCut DraftA

Add property keyframes (scale, position, rotation, opacity, ...) to an existing track for animation.

Args:

  • draft_id (string, required): From capcut_create_draft.

  • track_name (string, required): Name of the track to animate.

  • property_types (string[], required): Properties to animate, e.g. ['scale_x', 'scale_y', 'alpha'].

  • times (number[], required): Keyframe timestamps in seconds — same length as values.

  • values (string[], required): Keyframe values matching each timestamp.

  • extra_params: Any additional VectCutAPI field not modeled above.

Returns: JSON confirming the keyframes were added.

Example: animate a zoom-in — property_types=['scale_x','scale_y'], times=[0,2], values=['1.0','1.5'].

Inputs: times (required), values (required), draft_id (required), track_name (required), +2 more.

capcut_create_draftCreate CapCut DraftA

Create a new CapCut/Jianying video draft (project). This must be called first — every other capcut_* tool needs the draft_id it returns.

Args:

  • width (number): Canvas width in pixels. Default 1080.

  • height (number): Canvas height in pixels. Default 1920 (portrait). Use 1920x1080 for landscape.

Returns: JSON including result.draft_id (string) — pass this to all subsequent add_*/save_draft calls.

Example: Use when starting any new video project, e.g. "make a 9:16 short" -> width=1080, height=1920.

Inputs: width, height.

capcut_save_draftSave CapCut DraftA
Idempotent

Save/finalize a draft so it can be opened in CapCut/Jianying. Call this last, after adding all desired tracks/effects.

Args:

  • draft_id (string, required): From capcut_create_draft.

Returns: JSON including result.draft_url and/or the local draft folder path. Per VectCutAPI docs, saving generates a folder starting with 'dfd_' next to capcut_server.py — copy it into your CapCut/Jianying drafts directory to open it in the app.

Note: safe to call multiple times on the same draft_id (re-saves with current state).

Inputs: draft_id (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 10 tools

    Disambiguation5/5

    Each tool targets a distinct resource/action: draft creation vs. individual media types (text, video, audio, image, subtitle, effect, sticker, keyframe) vs. save. Even text vs. subtitle are explicitly disambiguated with usage notes.

    Naming Consistency5/5

    All tools share the 'capcut_' prefix followed by a consistent verb_noun structure (create_draft, add_text, add_video, save_draft). Naming is predictable and uniform.

    Tool Count5/5

    10 tools is well-scoped for a video editing domain, covering the essential creation pipeline without bloat. Each tool earns its place.

    Completeness4/5

    The surface covers the full workflow from draft creation through adding all major asset types and finalizing. Minor gaps like deletion or editing of added elements exist, but are not core to the draft-building purpose.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers