Skip to main content
Glama

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.

What it covers: import, cutting on words, timing, transitions, titles and captions, audio, effects, analysis (transcripts, beats, faces, tracking, scenes), compositing, motion graphics and stills from HTML, voiceover, cut-outs, stems, stabilizing, upscaling, lip-sync, previews, QA checks, and export to MP4, ProRes, GIF and audio or to Final Cut, Premiere and Resolve (FCPXML, OTIO, EDL). Every tool: cuttingfloor.ai/features. Use it from Kazi, Claude, ChatGPT or any MCP app.

Use it hosted

Sign up at cuttingfloor.ai (three days free), then add https://api.cuttingfloor.ai/mcp as a remote MCP server in Claude, ChatGPT, Cursor, Kazi or any client that takes one. The client opens the sign-in itself (OAuth). Nothing to install; transcription, voiceover, cutouts and rendering run on our servers. The official MCP Registry entry lists the same address.

Code that doesn't speak MCP calls the same tools as plain HTTP with a key from your account page (cf_…): POST https://api.cuttingfloor.ai/v1/<tool> with the tool's arguments as a JSON object answers its result, and /openapi.json describes every tool (OpenAPI 3.1). Refusals come back as HTTP error statuses with {code, message, hint}.

curl https://api.cuttingfloor.ai/v1/timeline.create \
  -H 'Authorization: Bearer cf_…' -H 'Content-Type: application/json' \
  -d '{"name": "First edit", "sequence": {"width": 1080, "height": 1920, "fps": {"num": 30, "den": 1}}}'

Related MCP server: Lazynext MCP Server

Run it yourself

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 HTML for create.motion and create.still renders. 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, using 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):

On your machine

In the container

What

$CUTTINGFLOOR_MEDIA (default ~/Movies)

/media/videos (read-only)

Footage. Import with {"path": "/media/videos/clip.mp4"}

$CUTTINGFLOOR_EXPORTS (default ~/cuttingfloor/exports)

/exports

Finished exports

Docker volume cuttingfloor-data

/data

Timelines, proxies, jobs (with time limits)

Provider keys are yours (bring your own) and go in the same .env, or in Docker secrets (/run/secrets/<name lower-cased>). They never pass through a tool, and video://server/health shows only whether each is set. create.lipsync needs SYNC_API_KEY from sync. labs (Settings → API keys); they bill your account for each second sent. Run docker compose up -d after adding one.

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. media.seek finds moments from plain words, so an agent doesn't have to watch the whole video: give it criteria like {too_dark: "the faces are too dark to make out their eyes", demo: "the product dashboard fills the screen"} and it returns the stretches of a video, or of an edit as it renders, where each one holds, with the best frame of each. Use it to check quality, find where something starts, pick shots, spot changes or find room for a title. TypeSafe Jev judges the frames and needs TYPESAFE_API_KEY.

  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. create.lipsync makes someone on camera say new words: give the video, the new speech (a re-recorded line or a voiceover) and the span of the video to change, and their mouth is redrawn to match by sync. labs on your own key (SYNC_API_KEY locally, the X-Cuttingfloor-Key-Sync header hosted). Only the span is sent; the result is that span, to place over the original.

  12. 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.

  13. 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.

  14. export.video in a format: mp4_h264, mp4_h264_fast, mp4_av1, mov_prores_422hq, gif, wav or mp3, at the sequence size, and overrides for another size, frame rate, bitrate or quality (video://catalog/presets). The result has a signed download URL and, locally, the file in your exports folder.

  15. 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.

Provider keys hosted come from the client, never from the server's environment: the MCP client sends each one as a header in its server config, X-Cuttingfloor-Key-<Provider>, for example X-Cuttingfloor-Key-Sync: <your sync. labs key> for create.lipsync. The key is used for that request and the job it starts, then dropped; it is never stored or logged. A tool that needs a key you haven't sent answers credential_required, naming the header.

{ "mcpServers": { "cuttingfloor": { "url": "https://api.cuttingfloor.ai/mcp", "headers": { "X-Cuttingfloor-Key-Sync": "<key>" } } } }

Variable

Default

CUTTINGFLOOR_DATA

/data

Data root

CUTTINGFLOOR_MAX_JOBS

cores ÷ 4

Concurrent imports, exports and QA runs (sandbox jobs queue in the sandbox instead)

CUTTINGFLOOR_HEAVY_JOBS

1

Concurrent create.cutout and create.stems runs, in their own slots apart from the jobs above

CUTTINGFLOOR_SHORT_JOBS

1

Extra job slots only short jobs take (an analysis, check or export of at most CUTTINGFLOOR_SHORT_JOB_SECONDS of media), so they never wait behind long running ones

CUTTINGFLOOR_SHORT_JOB_SECONDS

60

How much media a job may read and still count as short

CUTTINGFLOOR_STALL_SECONDS

300

A running job whose progress hasn't moved for this long (or a quarter of a second per second of media it reads, if longer) is ended with a stalled error and its slot freed

CUTTINGFLOOR_MAX_RENDERS

cores ÷ 2, at least 2

Renders (melt, encodes, transcription) at once, jobs and inline previews together; the rest wait their turn

CUTTINGFLOOR_OUTPUT_URL_TTL_HOURS

24

Signed download link lifetime

CUTTINGFLOOR_MAX_DOWNLOAD_BYTES

10 GiB

Size cap for URL imports and uploads

CUTTINGFLOOR_MOTION_URL

unset (compose sets it)

The sandbox for create.motion and create.still; without it those tools explain how to start one

CUTTINGFLOOR_MOTION_WORKERS

one per two CPUs, up to 4

Browsers that share a create.motion render; set on the sandbox

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

Layout

Path

What

apps/cli

cuttingfloor serve (HTTP), cuttingfloor mcp (stdio) and cuttingfloor motion-worker (the sandbox role)

apps/hosted

The HTTP node: MCP endpoint, signed downloads and uploads, API keys and script keys

packages/server

MCP tools, resources and the Tasks adapter

packages/schema

Zod schemas for every tool, the timeline document and errors

packages/core

Timeline document, edit math, content hashing, storage with TTLs

packages/engine

FFmpeg and MLT as subprocesses: probe, conform, proxies, frames, export, QA

packages/motion

The sandbox worker: pages rendered frame by frame on a virtual clock, one at a time

tools/

Native helpers built into the image (cf-vision, cf-segment) and the sandbox's Chromium wrapper and seccomp profile

packages/jobs

File-backed job store and runner behind MCP Tasks and job.*

packages/credentials

Bring-your-own provider keys

Licence

AGPL-3.0. Use it, change it and run it yourself. If you run a changed version as a service for other people, publish your changes under the same licence. The hosted service at cuttingfloor.ai runs this code.

Tool Schema Changelog

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

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to edit talking-head videos locally by transcribing footage, applying validated edit operations like cutting fillers and silences, adding zooms, captions, looks and branding, and checking results with rendered previews. Agents can also read pinned editor feedback notes with annotated frames, resolve them, and export MP4, SRT or OTIO while the user watches changes live.
      52 npm
      1
      MIT