# spectrika/capcut-mcp architecture

> Architecture diagram of the GitHub repository spectrika/capcut-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/spectrika/capcut-mcp
- Repository: https://github.com/spectrika/capcut-mcp

## Overview

capcut-mcp is an MCP server that lets AI clients create CapCut 9.3 drafts and edit existing projects. The main workflow is client tool calls into the server, followed by draft creation or project loading, timeline operations, and writing project files to CapCut’s projects directory. README documents additional media, text, effects, masks, and project-management tools. `entry.py` was not sampled, so its internal dispatch structure is represented only at the documented tool level; `timeline_edit.py` is shown as the editing layer it identifies itself as serving.

Main entry points: [`entry.py`](https://github.com/spectrika/capcut-mcp/blob/main/entry.py) (MCP Server), [`timeline_edit.py`](https://github.com/spectrika/capcut-mcp/blob/main/timeline_edit.py) (Timeline Operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["MCP Interface"]
  node_server["MCP Server<br/>[entry.py]"]
  node_health["Health Check<br/>[entry.py]"]
end

subgraph group_projects["Project Workflows"]
  node_draft["Draft Creation<br/>[entry.py]"]
  node_media_tools["Media Tools<br/>[entry.py]"]
  node_captions["Captions and Text<br/>[entry.py]"]
  node_effects["Effects and Stickers<br/>[entry.py]"]
  node_keyframes["Video Keyframes<br/>[entry.py]"]
  node_projects_list["Project Discovery<br/>[entry.py]"]
  node_project_open["Project Loading<br/>[entry.py]"]
  node_draft_describe["Draft Description<br/>[entry.py]"]
  node_save_draft["Draft Saving<br/>[entry.py]"]
end

subgraph group_editing["Timeline Editing"]
  node_timeline_tools["Range Editing<br/>[entry.py]"]
  node_segment_tools["Segment Editing<br/>[entry.py]"]
  node_text_edit["Text Editing<br/>[entry.py]"]
  node_track_edit["Track Settings<br/>[entry.py]"]
  node_blur_mask["Blur and Masks<br/>[entry.py]"]
  node_timeline_engine["Timeline Operations<br/>[timeline_edit.py]"]
end

subgraph group_storage["Project and Media I/O"]
  node_project_dir["CapCut Projects"]
  node_media_files["Media Files"]
end

node_client(("MCP Client"))
node_capcut(("CapCut Desktop"))

node_client -->|"calls tools"| node_server
node_server -->|"dispatches"| node_health
node_server -->|"dispatches"| node_draft
node_server -->|"dispatches"| node_media_tools
node_server -->|"dispatches"| node_captions
node_server -->|"dispatches"| node_effects
node_server -->|"dispatches"| node_keyframes
node_server -->|"dispatches"| node_projects_list
node_server -->|"dispatches"| node_project_open
node_server -->|"dispatches"| node_draft_describe
node_server -->|"dispatches"| node_timeline_tools
node_server -->|"dispatches"| node_segment_tools
node_server -->|"dispatches"| node_text_edit
node_server -->|"dispatches"| node_track_edit
node_server -->|"dispatches"| node_blur_mask
node_server -->|"dispatches"| node_save_draft
node_server -->|"uses"| node_timeline_engine
node_media_tools -->|"reads media"| node_media_files
node_captions -->|"reads subtitles"| node_media_files
node_projects_list -->|"lists projects"| node_project_dir
node_project_open -->|"opens project"| node_project_dir
node_save_draft -->|"writes project"| node_project_dir
node_capcut -->|"opens projects"| node_project_dir

click node_server "https://github.com/spectrika/capcut-mcp/blob/main/entry.py"
click node_health "https://github.com/spectrika/capcut-mcp/blob/main/entry.py"
click node_draft "https://github.com/spectrika/capcut-mcp/blob/main/entry.py"
click node_media_tools "https://github.com/spectrika/capcut-mcp/blob/main/entry.py"
click node_captions "https://github.com/spectrika/capcut-mcp/blob/main/entry.py"
click node_effects "https://github.com/spectrika/capcut-mcp/blob/main/entry.py"
click node_keyframes "https://github.com/spectrika/capcut-mcp/blob/main/entry.py"
click node_projects_list "https://github.com/spectrika/capcut-mcp/blob/main/entry.py"
click node_project_open "https://github.com/spectrika/capcut-mcp/blob/main/entry.py"
click node_draft_describe "https://github.com/spectrika/capcut-mcp/blob/main/entry.py"
click node_timeline_tools "https://github.com/spectrika/capcut-mcp/blob/main/entry.py"
click node_segment_tools "https://github.com/spectrika/capcut-mcp/blob/main/entry.py"
click node_text_edit "https://github.com/spectrika/capcut-mcp/blob/main/entry.py"
click node_track_edit "https://github.com/spectrika/capcut-mcp/blob/main/entry.py"
click node_blur_mask "https://github.com/spectrika/capcut-mcp/blob/main/entry.py"
click node_timeline_engine "https://github.com/spectrika/capcut-mcp/blob/main/timeline_edit.py"
click node_save_draft "https://github.com/spectrika/capcut-mcp/blob/main/entry.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server,node_health,node_client toneBlue
class node_draft,node_media_tools,node_captions,node_effects,node_keyframes,node_projects_list,node_project_open,node_draft_describe,node_save_draft toneAmber
class node_timeline_tools,node_segment_tools,node_text_edit,node_track_edit,node_blur_mask,node_timeline_engine toneMint
class node_project_dir,node_media_files toneRose
class node_capcut toneIndigo
```

## Components

### MCP Interface

- [MCP Server](https://github.com/spectrika/capcut-mcp/blob/main/entry.py): `entry.py`
- [Health Check](https://github.com/spectrika/capcut-mcp/blob/main/entry.py): `entry.py`

### Project Workflows

- [Draft Creation](https://github.com/spectrika/capcut-mcp/blob/main/entry.py): `entry.py`
- [Media Tools](https://github.com/spectrika/capcut-mcp/blob/main/entry.py): `entry.py`
- [Captions and Text](https://github.com/spectrika/capcut-mcp/blob/main/entry.py): `entry.py`
- [Effects and Stickers](https://github.com/spectrika/capcut-mcp/blob/main/entry.py): `entry.py`
- [Video Keyframes](https://github.com/spectrika/capcut-mcp/blob/main/entry.py): `entry.py`
- [Project Discovery](https://github.com/spectrika/capcut-mcp/blob/main/entry.py): `entry.py`
- [Project Loading](https://github.com/spectrika/capcut-mcp/blob/main/entry.py): `entry.py`
- [Draft Description](https://github.com/spectrika/capcut-mcp/blob/main/entry.py): `entry.py`
- [Draft Saving](https://github.com/spectrika/capcut-mcp/blob/main/entry.py): `entry.py`

### Timeline Editing

- [Range Editing](https://github.com/spectrika/capcut-mcp/blob/main/entry.py): `entry.py`
- [Segment Editing](https://github.com/spectrika/capcut-mcp/blob/main/entry.py): `entry.py`
- [Text Editing](https://github.com/spectrika/capcut-mcp/blob/main/entry.py): `entry.py`
- [Track Settings](https://github.com/spectrika/capcut-mcp/blob/main/entry.py): `entry.py`
- [Blur and Masks](https://github.com/spectrika/capcut-mcp/blob/main/entry.py): `entry.py`
- [Timeline Operations](https://github.com/spectrika/capcut-mcp/blob/main/timeline_edit.py): `timeline_edit.py`

### Project and Media I/O

- **CapCut Projects**
- **Media Files**

### Other components

- **MCP Client**
- **CapCut Desktop**

## Connections

- MCP Client → MCP Server: calls tools (evidence: `README.md`)
- MCP Server → Health Check: dispatches (evidence: `README.md`)
- MCP Server → Draft Creation: dispatches (evidence: `README.md`)
- MCP Server → Media Tools: dispatches (evidence: `README.md`)
- MCP Server → Captions and Text: dispatches (evidence: `README.md`)
- MCP Server → Effects and Stickers: dispatches (evidence: `README.md`)
- MCP Server → Video Keyframes: dispatches (evidence: `README.md`)
- MCP Server → Project Discovery: dispatches (evidence: `README.md`)
- MCP Server → Project Loading: dispatches (evidence: `README.md`)
- MCP Server → Draft Description: dispatches (evidence: `README.md`)
- MCP Server → Range Editing: dispatches (evidence: `README.md`)
- MCP Server → Segment Editing: dispatches (evidence: `README.md`)
- MCP Server → Text Editing: dispatches (evidence: `README.md`)
- MCP Server → Track Settings: dispatches (evidence: `README.md`)
- MCP Server → Blur and Masks: dispatches (evidence: `README.md`)
- MCP Server → Draft Saving: dispatches (evidence: `README.md`)
- MCP Server → Timeline Operations: uses (evidence: `timeline_edit.py`)
- Media Tools → Media Files: reads media (evidence: `README.md`)
- Captions and Text → Media Files: reads subtitles (evidence: `README.md`)
- Project Discovery → CapCut Projects: lists projects (evidence: `README.md`)
- Project Loading → CapCut Projects: opens project (evidence: `README.md`)
- Draft Saving → CapCut Projects: writes project (evidence: `README.md`)
- CapCut Desktop → CapCut Projects: opens projects (evidence: `README.md`)