capcut-mcp
This server allows programmatic creation and editing of CapCut desktop video drafts by manipulating local project files (draft_content.json and draft_meta_info.json), which can then be opened in CapCut for preview and export.
Create & manage drafts
create_draft— Initialize an empty project with a custom name, canvas size (default 1080×1920), and frame rate (default 30fps)list_drafts— Browse all drafts in the local CapCut drafts folderget_draft— Retrieve a full timeline summary including tracks, segments, timings, and total duration
Add media
add_video— Insert a video file with control over position (x,y), scale, rotation, volume, timeline placement (atSeconds), clip duration, and source start offset; duration/dimensions are auto-detected viaffprobeadd_image— Place a still image with configurable on-screen duration (default 5s), position, scale, and rotationadd_audio— Attach music or voiceover with volume control, timeline positioning, and source trimmingadd_text— Insert text captions/titles with control over content, color, font size, position, scale, rotation, and display duration (default 3s)
Automatic track management — Segments append to the end of their track by default; overlapping segments are automatically placed on a new track so overlays work seamlessly.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@capcut-mcpCreate a draft called 'My Video' and add a 10-second video clip"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
| Creates an empty draft (default canvas 1080x1920 @ 30fps) |
| Lists drafts in the drafts folder |
| Returns the timeline: tracks, segments, timings |
| Adds a video clip (duration/dimensions detected via ffprobe) |
| Adds a still image (default 5s on screen) |
| Adds music or voiceover to an audio track |
| 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".
Related MCP server: CapCut MCP
Setup
pnpm install
pnpm buildRegister in Claude Code:
claude mcp add --scope user capcut -- node /absolute/path/to/capcut-mcp/dist/index.jsConfiguration
Env var | Default | Purpose |
|
| 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 --> DraftDocumentPatterns in play:
Facade —
DraftServiceexposes one use case per tool and owns the workflow.Repository —
FsDraftRepositoryisolates all disk I/O and the meta-info bookkeeping.Factory —
DraftContentFactory/MaterialFactory/SegmentFactoryencapsulate CapCut's JSON blocks.Strategy + Chain of Responsibility —
MediaProbeimplementations try ffprobe first, thensips.Dependency Injection — constructor injection everywhere;
IdGeneratorandClockare injected too, which keeps every unit test deterministic (seesrc/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
~/Moviesor~/Documents). CapCut marks files under/tmpas "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)Available Tools
7 toolsadd_audioAdd audio clipB
Adds an audio file (music, voiceover) to a draft audio track.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Absolute path to the audio file (supports ~). | |
| draft | Yes | Target draft name. | |
| volume | No | Clip volume, 0..2. Default 1. | |
| atSeconds | No | Timeline position in seconds. Defaults to the end of the track. | |
| durationSeconds | No | Clip length in seconds. Defaults to the full audio. | |
| sourceStartSeconds | No | Where the clip starts inside the source audio. Default 0. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description lacks details on side effects (e.g., replaces or appends? requires existing draft?), authorization needs, or error behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, 13 words, front-loaded and to the point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, no annotations, and description is too brief for a 6-parameter tool; lacks info on return values, error conditions, and usage context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% so parameters are already described; description adds no extra semantic context beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'adds' and resource 'audio file (music, voiceover) to a draft audio track', distinguishing it from siblings like add_image, add_text, add_video.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, no prerequisites or exclusions mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
add_imageAdd imageB
Adds a still image to a draft video track.
| Name | Required | Description | Default |
|---|---|---|---|
| x | No | Horizontal offset from canvas center, -1..1. Default 0. | |
| y | No | Vertical offset from canvas center, -1..1. Default 0. | |
| path | Yes | Absolute path to the image file (supports ~). | |
| draft | Yes | Target draft name. | |
| scale | No | Uniform scale factor. Default 1. | |
| rotation | No | Rotation in degrees. Default 0. | |
| atSeconds | No | Timeline position in seconds. Defaults to the end of the track. | |
| durationSeconds | No | How long the image stays on screen. Default 5. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose side effects. It does not mention whether the operation modifies the draft, requires specific permissions, handles errors (e.g., missing file), or returns any value. This is insufficient for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that is front-loaded and easy to parse. It could include more context without significant bloat, but is not wasteful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 8 parameters, no output schema, and no annotations, the description is too sparse. It does not explain what a 'draft video track' is, prerequisites, or likely outcomes, leaving significant gaps for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter having a detailed description (e.g., range, default). The tool description adds no additional parameter info, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Adds'), the resource ('still image'), and the target ('draft video track'). This effectively distinguishes it from sibling tools like add_audio, add_text, and add_video that add different media types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly indicates use for adding still images, but does not explicitly state when to use this tool versus alternatives (e.g., add_video for animated content). No exclusions or prerequisites are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
add_textAdd text overlayC
Adds a text overlay (title, caption) to a draft text track.
| Name | Required | Description | Default |
|---|---|---|---|
| x | No | Horizontal offset from canvas center, -1..1. Default 0. | |
| y | No | Vertical offset from canvas center, -1..1. Default 0. | |
| text | Yes | Text content to display. | |
| color | No | Text color as #RRGGBB. Default #FFFFFF. | |
| draft | Yes | Target draft name. | |
| scale | No | Uniform scale factor. Default 1. | |
| fontSize | No | CapCut font size. Default 15. | |
| rotation | No | Rotation in degrees. Default 0. | |
| atSeconds | No | Timeline position in seconds. Defaults to the end of the track. | |
| durationSeconds | No | How long the text stays on screen. Default 3. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description alone must disclose behavioral traits. It only states 'adds' without mentioning side effects, permissions, or what happens if the draft doesn't exist. No info on idempotency, track creation, or response behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is a single, front-loaded sentence with no filler. It is concise but could be expanded slightly to improve completeness without being verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 10 parameters, no output schema, and no annotations, the description is insufficient. It does not specify required context (e.g., draft must exist), ordering, or the nature of the text overlay on the timeline. Completeness is inadequate for accurate tool selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description covers all 10 parameters, so baseline is 3. The description adds no additional parameter semantics beyond the schema. It does not explain parameter relationships or defaults beyond what's in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it adds a text overlay to a draft text track. The verb 'adds' and resource 'text overlay' are specific. It distinguishes from sibling tools like add_audio or add_image, though it could be more precise about what constitutes a text overlay.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like add_image or add_video. Implied usage is for adding text, but no explicit when-not or prerequisites (e.g., draft must exist). Sibling tools are listed but not referenced.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
add_videoAdd video clipB
Adds a video file to a draft video track. Duration and dimensions are detected with ffprobe when available.
| Name | Required | Description | Default |
|---|---|---|---|
| x | No | Horizontal offset from canvas center, -1..1. Default 0. | |
| y | No | Vertical offset from canvas center, -1..1. Default 0. | |
| path | Yes | Absolute path to the video file (supports ~). | |
| draft | Yes | Target draft name. | |
| scale | No | Uniform scale factor. Default 1. | |
| volume | No | Clip volume, 0..2. Default 1. | |
| rotation | No | Rotation in degrees. Default 0. | |
| atSeconds | No | Timeline position in seconds. Defaults to the end of the track. | |
| durationSeconds | No | Clip length in seconds. Defaults to the full video. | |
| sourceStartSeconds | No | Where the clip starts inside the source video. Default 0. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It adds value by stating that duration and dimensions are auto-detected via ffprobe when available, but it does not disclose other important behaviors such as error handling, side effects (e.g., replacing existing clips), or dependencies.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no wasted words. It is front-loaded with the core action and includes a useful behavioral note. It could be slightly more structured but is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (10 parameters, no output schema) and absence of annotations, the description is incomplete. It does not explain the return value, error conditions, or what happens when ffprobe is unavailable. An agent would lack critical context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the input schema already documents all parameters. The description does not add any additional meaning beyond what the schema provides, so baseline score 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (adds a video file) and the target resource (draft video track). It distinguishes itself from sibling tools like add_audio, add_image, and add_text by specifying 'video file' and 'video track'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, no prerequisites, and no conditions for use. The ffprobe mention is a behavioral detail, not a usage guideline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_draftCreate CapCut draftA
Creates a new empty CapCut draft (project) in the local drafts folder. Open it later with CapCut desktop.
| Name | Required | Description | Default |
|---|---|---|---|
| fps | No | Frames per second. Default 30. | |
| name | Yes | Draft name; also used as the project folder name. | |
| width | No | Canvas width in pixels. Default 1080. | |
| height | No | Canvas height in pixels. Default 1920 (9:16 vertical). |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries the full burden. It describes the creation of an empty draft and hints at post-creation action, but does not disclose what happens if a draft with the same name exists, permissions needed, or any side effects. Adequate but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with the primary purpose in the first sentence. No wasted words; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple creation tool with 4 parameters fully described in schema and no output schema, the description provides the core purpose but omits what the tool returns (e.g., draft ID) or any prerequisites. It is slightly incomplete for an agent to fully utilize without guessing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters. The description does not add any parameter-specific meaning beyond the schema, placing it at the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a new empty CapCut draft (project) in the local drafts folder. It includes a usage hint about opening with CapCut desktop. It is distinct from sibling tools which add media or list/get drafts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by stating 'Open it later with CapCut desktop,' but does not explicitly state when to use this tool versus alternatives or when not to use it. No exclusions or context for when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_draftInspect CapCut draftA
Returns the timeline of a draft: tracks, segments, timings and total duration.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Draft name. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only states what the function returns. It does not disclose that this is a read-only operation, whether the draft must exist, or error conditions. The agent lacks behavioral guidance beyond the output.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that immediately communicates the tool's purpose and what it returns. Every word is essential and nothing is superfluous.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with one parameter, the description adequately covers the core functionality and return value. It could mention that the draft must exist, but the overall completeness is high given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the lone parameter 'name' is described as 'Draft name.' The tool description adds no additional meaning or constraints beyond the schema, meeting the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns the timeline of a draft, listing specific components like tracks, segments, timings, and duration. This action is distinct from sibling tools that add content or create/list drafts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is used to inspect an existing draft but does not explicitly state when to use it versus alternatives or provide prerequisites. The context of needing a draft name is implied but not elaborated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_draftsList CapCut draftsB
Lists the CapCut drafts found in the local drafts folder.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description lacks any behavioral traits such as read-only nature, authentication requirements, or side effects. It only states the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, well-structured sentence that efficiently conveys the tool's purpose with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description is too minimal. It does not specify the format or details of the returned list, leaving an agent without sufficient context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero parameters, the schema coverage is 100% and no additional parameter explanation is needed. However, the description adds no extra meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Lists' and identifies the resource as 'CapCut drafts', clearly distinguishing from sibling tools that add or create content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use list_drafts versus get_draft or other siblings. The description does not provide any context for choosing this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
7 tool updates
v0.1.0- First observed
add_audio - First observed
add_image - First observed
add_text - First observed
add_video - First observed
create_draft - First observed
get_draft - First observed
list_drafts
TDQS
Scored across 7 tools
Each tool targets a distinct media type (audio, image, text, video) or draft operation (create, get, list), with no overlapping purposes.
All tools follow a consistent verb_noun pattern (e.g., add_audio, create_draft, list_drafts), making them predictable.
7 tools is well-scoped for a video editing assistant, covering essential draft and media operations without bloat.
Covers draft creation, listing, and adding media, but lacks remove/update operations for media or export functionality, which are minor gaps.
Maintenance
Related MCP Connectors
AI-native video editing OS — timeline editing, generation, color, and export as MCP tools.
A real timeline video editor for AI agents: journaled edits, FFmpeg/MLT rendering, exports
Generate video and images, edit them on a real multi-track timeline, and export an MP4.
AI editor to build, animate & export layered short-form video projects via one tool catalog.
Related MCP Servers
- FlicenseNot gradedqualityFmaintenanceEnables video editing operations such as trimming, merging, adding audio/text/effects, and exporting via MCP protocol, leveraging CapCut core functionalities.93-
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants like Claude Code to build and edit CapCut video projects locally by creating drafts, adding media and effects, and saving projects that open in CapCut desktop.1Apache 2.0
- AlicenseBqualityCmaintenanceAn MCP server for inspecting and editing CapCut Desktop draft projects through local, version-safe timeline operations.53MIT
- AlicenseBqualityAmaintenanceEnables AI to create and edit local Jianying/CapCut draft projects on macOS from videos, images, audio, and text, supporting editable subtitles, keyframes, motion presets, and batch operations via MCP tools.222MIT