opencut-mcp

MCP (Model Context Protocol) server for the OpenCut classic video editor. Lets an LLM agent (Claude Code, Cline, etc.) drive the timeline via window.__editor in a Playwright-controlled browser.

Status: PoC for a kenimoto.dev article series.

Runs against a fork, not upstream

This server does not target opencut-app/opencut-classic (archived). It targets the kenimo49/opencut-classic fork, which carries a small patch series that exposes internals needed for automation. Point your docker compose / bun dev:web at the fork's main.

The fork may drift further from upstream as we add hooks — e.g. data-testid anchors for wait/assertion, or a headless-export toggle. Track the two together; a version of this server may not work against an arbitrary snapshot of the fork. Compatibility is pinned at repo level, not by semver (yet). The current commit of this server was validated against kenimo49/opencut-classic@a7443ec8.

Related MCP server: OpenCut Controller

Demo

scripts/demo.ts runs a full end-to-end sequence: create a project, upload a video

• audio file, place both on the timeline via auto-placement, split the video at 5s. The Playwright screencast below is that run recorded verbatim.

Tools

Running

# 1. Start the FORK of classic (docker + bun dev:web on 3000).
git clone https://github.com/kenimo49/opencut-classic.git
cd opencut-classic
# ... see that repo's README for docker compose + env.local setup
bun run dev:web   # http://localhost:3000

# 2. Install and run this MCP (in a separate shell):
cd ../opencut-mcp
bun install
bunx tsx src/index.ts   # stdio transport

# 3. Or the integration demo:
bunx tsx scripts/demo.ts

Env:

• OPENCUT_BASE_URL — default http://localhost:3000

• OPENCUT_HEADLESS — false to see the browser (WSLg / X11 required)

• OPENCUT_VIDEO_DIR — set to record a webm screencast of the browser

• OPENCUT_DEMO_PACE=slow — triples inter-step pauses in scripts/demo.ts

Notes discovered during PoC

1. Empty tracks are pruned every command via CommandManager reactor (editor/index.ts:playback.bindTimelineScope). Two-step addTrack + insertElement loses the track before the second call. Prefer insertElement with placement: { mode: "auto", trackType } — the command creates the track on demand and it survives because it has an element.

2. MediaTime is integer ticks, not seconds. TICKS_PER_SECOND is 120,000 at runtime. Convert via window.__opencut.mediaTimeFromSeconds({ seconds }) (Phase 1.1 exposure).

3. AudioElement discriminated union — uploads must carry sourceType: "upload" in addition to mediaId.

4. Editor page is /editor/[project_id]. Creating a project via the /projects UI is the boot path used by this server.

MIT.