Cuttingfloor MCP Server

cuttingfloor

A headless video editor for agents, as an MCP server. An agent imports footage, cuts it on a timeline with granular editing tools, looks at the result after every edit, checks it, and exports a file.

• Every edit returns a new timeline id, plus a preview image of the result. Timelines are immutable, so going back is just using an older id.
• Nothing is stored for you. Timelines, media and outputs live in a cache with a time limit (24 hours for timelines, 7 days for media and exports). Export to keep work.
• One Docker image runs locally (free) and hosted. Engines (FFmpeg, MLT) ship inside it; Docker is the only thing you install.

Status: Phase 3 in progress. Import, timelines, clip editing, timing (speed, ramps, reverse, freeze frames, roll/slip/slide, range extract, nested timelines), transitions, titles and captions, audio (gain, pan, fades, ducking, loudness), effects (colour, LUTs, blur, chroma key and more; EQ, compressor, denoise, pitch), analysis (transcripts, beats, faces, tracking), compositing (transforms, keyframes, masks, blend modes, animations), motion graphics and HTML stills (sandboxed), mattes, local voiceover with timed words, people cut-outs, previews, exact QA checks and H.264/ProRes export work end to end. Provider tools (ElevenLabs, OpenAI) and NLE interchange come next.

Run it

docker compose up -d          # local mode: one node on 127.0.0.1:8787, plus the motion sandbox

Compose starts two containers from the same image: cuttingfloor (the server) and cuttingfloor-motion, the sandbox where agent-written code runs: HTML for create.motion and create.still, and code.run scripts. The sandbox has no route out, no data volume, no capabilities, a read-only filesystem and fixed CPU, memory and process limits. Chromium's own sandbox stays on inside it, and each script runs in its own user, PID and network namespaces with no network at all; both use the seccomp profile at tools/motion/seccomp.json (Docker's default plus namespace creation). Run compose from a checkout of this repository so that file is there.

Connect an MCP client over Streamable HTTP:

{ "mcpServers": { "cuttingfloor": { "url": "http://127.0.0.1:8787/mcp" } } }

Or over stdio, for clients that only launch commands. The stdio process forwards to the running container, so long exports keep going after the client exits:

{ "mcpServers": { "cuttingfloor": { "command": "docker", "args": ["exec", "-i", "cuttingfloor", "cuttingfloor", "mcp"] } } }

Folders (set them in a .env next to compose.yaml, see .env.example):

The image includes /samples/sample.mp4 (10 s test pattern with a tone) and /samples/card.png to try things with nothing mounted.

On Docker Desktop for Mac, raise the memory limit for long 4K timelines; bind-mounted footage reads go through VirtioFS. On Linux, create the exports folder before the first start so it belongs to you.

How an agent uses it

1. media.import each file. It's long-running: a task for clients that support MCP Tasks, otherwise a job_id to poll with job.get. The media_id is usable once the job reports processing.
2. media.analyze turns media into data an agent can edit with: transcript (every word with its time; whisper.cpp on the CPU, the model downloads once), beats (tempo, beats, downbeats), faces (face boxes over time) and track (follow a region). Then cut by words with clip.add {source: {words: [i, j]}} and caption with caption.add {in_clip: {clip_id, segments}}, timed in the media's seconds.
3. timeline.create with a sequence ({width, height, fps: {num, den}}).
4. Edit: clip.add, clip.trim (with side for J/L cuts), clip.split, clip.move, clip.remove (with ripple), clip.link, track.*, or edit.batch to apply many edits at once, using {"$ref": "ops[0].clip_id"} for ids made earlier in the batch.
5. Time: clip.set_speed (constant rate, a speed-ramp curve, reverse; pitch is kept), clip.freeze, clip.roll, clip.slip, clip.slide, clip.replace, and range.extract / range.lift to cut a span out of every track at once. clip.add {nested_timeline_id} nests a whole timeline as one clip.
6. Transition: transition.add at the cut after a clip: dissolve, dip to black or white, wipes, slides, pushes, zooms, iris and spin. Linked audio crossfades at the same cut. By default the clips overlap and later clips move earlier; mode: "handles" uses source past the cut and moves nothing.
7. Text: title.add and caption.add (from segments with word timings, or from SRT/VTT) put text on a video track, rendered with libass: font, size, colour, outline, shadow, box, karaoke and word highlights, typewriter and word reveals. text.set restyles many at once. Fonts are listed at video://catalog/fonts; import your own .ttf/.otf with media.import and use it with font_media_id.
8. Audio: audio.set_gain (dB, with keyframes for rides), audio.set_pan, audio.fade and audio.set_master (gain and a limiter ceiling on the whole mix). Audio edits preview as a waveform image with the measured loudness.
9. Effects: filter.add on a clip, every clip on a track, or the whole timeline: colour (brightness, contrast, saturation, exposure, temperature, curves, LUTs imported as .cube), blur, sharpen, vignette, grain, glitch, pixelate, chroma key; for sound EQ, compressor, noise reduction, de-esser, dialogue enhance, reverb, echo, pitch. adjustment.add adds a clip whose effects change everything below it while it runs. The list with params is at video://catalog/effects.
10. Composite: put a clip on a higher video track, then clip.set_transform (position, scale, rotation, opacity, crop, flip, fit; any number can take keyframes with easing), clip.set_mask (rectangle, ellipse, linear, mirror, heart, star, polygon), clip.set_blend and clip.set_animation (entrance, exit and loop presets). The accepted names are resources at video://catalog/{name}.
11. Create: create.motion renders any animated HTML to a video with alpha, frame-exactly: CSS animations and transitions, the Web Animations API, SVG, canvas or WebGL drawn in requestAnimationFrame, timers, or a window.__seek(seconds) the page defines all run on a virtual clock the renderer steps one frame at a time. anime.js, three.js, Lottie and D3 load from lib/ (<script src="lib/anime.umd.min.js">). create.still renders an HTML page to a PNG, and create.matte makes a solid or gradient picture. Each returns a media_id for clip.add; the same recipe returns the same media. Pages can't reach the network, so images and fonts go in as assets (imported media) and are referred to as assets/<name>. create.voiceover speaks English text in one of 28 Kokoro voices on the CPU (the model, about 350 MB, downloads once) and times every word, so caption.add {in_clip} can caption it exactly. create.cutout removes the background behind a subject: any (BiRefNet; products, animals, objects, people; the default for pictures; needs about 3 GB of memory free for Docker) or people (MODNet; fast enough for video, the default there), keeping the sound.
12. Code: code.run runs a Node, Python or bash script in the sandbox for anything the tools don't cover: procedural or data-driven edits, generated graphics, custom FFmpeg or MLT work. Inside it every tool is a function, cf.domain.verb(args) (import { cf } from 'cuttingfloor'; Python from cuttingfloor import cf; bash cf clip.trim '{...}'), acting on the same media and timelines with the same checks. importFile(path) brings a file the script made in as media at once, and motion() / still() render pages right there. Inputs arrive in in/; files left in out/ come back as media, and *.timeline.json as timelines. So a script can lay down 300 beat-synced cuts and the agent refines them with single tools, or the tools build the edit and a script does the one odd thing.
13. Look: preview: "inline" on any edit returns the image; render.frames returns up to 16 frames as a contact sheet, or up to 4 at full size (size: "full") for thumbnails.
14. qa.check measures the render: gaps, offline media, frame count, loudness and true peak, plus black and silent stretches with the settings you give. Facts, no verdicts.
15. export.video with a preset: web_1080p_h264, master_prores_422hq, social_9x16_h264, web_1080p_av1, gif, audio_wav_48k or audio_mp3, and overrides for size, frame rate, bitrate or quality (video://catalog/presets). The result has a signed download URL and, locally, the file in your exports folder.
16. export.timeline hands the edit to another editor as FCPXML (Final Cut Pro, Resolve), OTIO (Premiere, Resolve) or a CMX 3600 EDL, or writes the captions as SRT or VTT, with warnings for what the format can't carry. media: "collect" zips the media alongside. timeline.get stays the lossless copy.

Time is integer frames at the sequence rate, end-exclusive. timeline.get returns the whole timeline as JSON; timeline.load restores it after it expires. video://server/health reports engine versions and limits.

Hosted mode

The same image with CUTTINGFLOOR_MODE=hosted: no path imports (URLs only), no exports folder, and every request needs Authorization: Bearer <key> from CUTTINGFLOOR_API_KEYS (owner:key,owner2:key2, or the cuttingfloor_api_keys Docker secret). Each key's owner has separate timelines, media and jobs. CUTTINGFLOOR_PUBLIC_URL is required: download links are built from it, and the server won't start without it.

Develop

pnpm install && pnpm check       # lint, typecheck, unit and protocol tests (Node 24+, pnpm 10)
docker build --target test .     # everything, including engine and end-to-end tests
docker build -t cuttingfloor:dev . && node scripts/smoke-image.ts cuttingfloor:dev
node scripts/smoke-motion.ts cuttingfloor:dev   # the sandbox in compose, attacked (pages and scripts)
node packages/sdk/scripts/generate.ts           # after changing a tool: regenerate the SDK's types

Layout

Licence

Not chosen yet. Until a licence is added, all rights are reserved.