Skip to main content
Glama

SkyCut

Local-first MCP server (stdio, TypeScript) that turns a folder of raw drone footage into a polished marketing cut, driven conversationally from Claude Code or Claude Desktop:

scan → analyze (vision) → footage graph → propose cut → human approve → render

Point it at a USB drive of raw drone video and produce a 60–90 second marketing edit with crossfades and an optional music bed. The source drive is treated as read-only; all derived artifacts (proxies, frames, timelines, renders) live in ~/SkyCut/projects/<slug>/ on the internal disk.

Requirements

  • Node 20+

  • ffmpeg + ffprobe — brew install ffmpeg (Apple Silicon videotoolbox hardware encoders used for all renders)

  • ANTHROPIC_API_KEY — for vision analysis and cut proposal

Related MCP server: MCP Research Tools

Install

npm install
npm run build

Claude Code

claude mcp add skycut --env ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY -- node /absolute/path/to/skycut/dist/index.js

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "skycut": {
      "command": "node",
      "args": ["/absolute/path/to/skycut/dist/index.js"],
      "env": { "ANTHROPIC_API_KEY": "sk-ant-..." }
    }
  }
}

Verify with MCP Inspector

npm run inspector

Workflow

A typical session, in plain conversation with Claude:

  1. skycut_list_volumes() — find the USB drive

  2. skycut_init_project("/Volumes/DJI/lodge-trip") — create the workspace

  3. skycut_scan_footage() — index clips, build 720p proxies (idempotent; unplug the drive afterwards if you like)

  4. skycut_analyze_footage() — Claude vision scores every 4s keyframe into a searchable footage graph (cached; asks before runs over 500 frames)

  5. skycut_propose_cut("Cinematic 90-second marketing cut, slow build, reveal the lodge at golden hour", 90) — AI director assembles timeline v1

  6. skycut_render_preview() — fast 720p render from proxies; watch it

  7. skycut_apply_timeline_edit({ edits: [...] }) — revise; every edit is a new immutable version

  8. skycut_render_final(2) — full-quality HEVC render from the originals (drive must be mounted)

Explore in between with skycut_search_moments({ subject: "lodge", min_aesthetic: 7 }) and skycut_project_status().

Web UI

A local chat UI (no auth — local use only) wraps the same core pipeline in a browser:

ANTHROPIC_API_KEY=sk-ant-... npm run web   # → https://dev.ecoworks.ca:3080
  • Chat agent — a Claude-driven agent with tool use over the SkyCut core (in-process, no MCP hop): propose cuts, search moments, apply edits, and render, with SSE-streamed progress bars and per-turn/session cost tracking

  • Footage panel (📁) — browse volumes/folders and open one as a read-only project source, drag-and-drop video uploads (into ~/SkyCut/uploads), scan + analyze with live progress and the vision cost gate, and switch between projects (chat archives on switch)

  • Timeline panel (🎞️) — visual shot strip with keyframe thumbnails; drag shots to reorder, drag shot edges to retrim (every drop saves a new immutable version); click a shot for trim/speed/source details; compare any two versions with a color-coded diff; a playhead tracks the matching preview player and clicking a shot seeks it

  • Music (🎵) — search royalty-free tracks (Jamendo), preview in-chat, download into ~/SkyCut/music

  • Renders — previews and finals embed as inline players (same-origin media with HTTP range support)

  • About — in-app changelog, how-it-works guide, and roadmap

The web server operates on the active project (the one last opened with skycut_init_project). Chat history persists across restarts; edits made in the panel and in chat share one code path and one version history.

Tools

Tool

Purpose

skycut_health()

Dependency status (ffmpeg, encoders, API key)

skycut_list_volumes()

Mounted volumes with free space

skycut_init_project(source_path, name?)

Create/reopen a project; source is read-only

skycut_scan_footage()

ffprobe metadata + manifest + SQLite + 720p proxies

skycut_analyze_footage(force?, confirm?)

Vision analysis → scored segments (footage graph)

skycut_search_moments(filters)

Query segments by subject/movement/quality/score/text

skycut_propose_cut(brief, duration_s, style?, music_path?)

AI director → validated timeline version

skycut_get_timeline(version?)

Timeline JSON + shot list

skycut_apply_timeline_edit(edits | timeline)

Structured diff → new immutable version

skycut_render_preview(version?)

720p from proxies

skycut_render_final(version)

Up-to-4K HEVC from originals; explicit version required

skycut_project_status()

Pipeline state + drive mount check

Guardrails

  • The USB source is never written to; unplugging it mid-session degrades gracefully (proxies keep previews working)

  • Timeline versions are immutable — edits always create v<N+1>

  • Nothing is ever auto-finalized: skycut_render_final requires an explicit version

  • Every ffmpeg command is logged to the project's logs/ffmpeg.log

  • Vision runs needing more than 500 frames report an estimated cost and wait for confirmation

Development

npm run build     # tsc (the web server imports from dist/ — rebuild before `npm run web`)
npm test          # vitest — vision/director mocked; ffmpeg integration uses generated testsrc clips
npm run inspector # poke the MCP server interactively
npm run web       # chat UI on https://dev.ecoworks.ca:3080 (needs ANTHROPIC_API_KEY)

Documentation

  • docs/README.md — architecture, design decisions, workspace layout, troubleshooting, extending

  • docs/TOOLS.md — complete tool API reference, timeline schema, edit operations, error conventions

  • CHANGELOG.md — version history

  • SkyCut Overview deck — 10-slide presentation: the problem, pipeline, footage graph, director, guardrails, both front ends, stack and roadmap (private Claude artifact — ask the owner for access)

  • prompt_plan.md (original spec) and progress.md (per-phase build history)

Available Tools

12 tools
skycut_analyze_footageAnalyze footage (vision)A
Idempotent

Sample keyframes (1 per 4s) from every scanned clip and analyze them with Claude vision to build the footage graph: scored segments with subjects, camera movement, and quality flags. Cached — already-analyzed clips are skipped unless force=true. If the run needs >500 frames, returns a cost estimate instead; re-call with confirm=true to proceed.

Inputs: force, confirm.

skycut_apply_timeline_editEdit timelineA

Apply structured edits to the latest (or given) timeline version, or replace it wholesale. Versions are immutable — the result is always saved as a NEW version. Ops: insert {at_index, clip}, remove {id}, reorder {id, to_index}, retrim {id, in_s?, out_s?, speed?}, set_transition {id, transition|null}, set_music {music|null}. Example: { edits: [{ op: "retrim", id: "c3", out_s: 51.0 }] }

Inputs: edits, timeline, base_version.

skycut_get_timelineGet timelineA
Read-only

Return a timeline version (latest by default) as JSON plus a human-readable shot list.

Inputs: version.

skycut_healthSkyCut health checkA
Read-only

Report status of required dependencies (Node, ffmpeg, ffprobe, videotoolbox encoders, ANTHROPIC_API_KEY). Run this first if any other tool returns unexpected errors.

Inputs: no named parameters.

skycut_init_projectInitialize projectA
Idempotent

Create (or reopen) a SkyCut project for a folder of source footage and make it the active project. The source path is treated as READ-ONLY; all derived files go to the workspace under ~/SkyCut/projects/. Example: skycut_init_project({ source_path: "/Volumes/DJI/ogoki-lodge" })

Inputs: source_path (required), name.

skycut_list_volumesList mounted volumesA
Read-only

List volumes under /Volumes with free/total space (GB), to help pick the source drive for skycut_init_project.

Inputs: no named parameters.

skycut_project_statusProject statusA
Read-only

Pipeline state for the active project: scan/analysis progress, timeline versions, renders, and whether the source drive is currently mounted.

Inputs: no named parameters.

skycut_propose_cutPropose cutA

Have the AI director assemble a timeline from the footage graph: narrative arc, varied movement, 3-8s shots, crossfades, within ±5% of the target duration. Saves an immutable timeline version for review — NEVER renders anything itself. Example: skycut_propose_cut({ brief: "90s cinematic cut for a fly-in fishing lodge, slow build to reveal", duration_s: 90 })

Inputs: brief (required), duration_s (required), style, music_path.

skycut_render_finalRender finalA

Full-quality render (HEVC videotoolbox, up to 4K, AAC audio) from the ORIGINAL files on the source drive. Requires an explicit timeline version — never renders 'latest' implicitly. The drive must be mounted.

Inputs: version (required).

skycut_render_previewRender previewA

Fast 720p preview render of a timeline version (latest by default) from proxies — works even with the source drive unplugged. Output goes to the project renders/ folder.

Inputs: version.

skycut_scan_footageScan footageA
Idempotent

Recursively index video files (.mp4/.mov/.mts/.mkv) under the active project's source path: ffprobe metadata into the footage database + manifest.json, and build 720p proxies for previews. Idempotent — re-running skips clips and proxies that already exist. The source is never modified.

Inputs: no named parameters.

skycut_search_momentsSearch momentsA
Read-only

Query the footage graph for segments by subject, camera movement, quality, aesthetic score, or free text against notes. Example: { subject: "lodge", movement: "orbit", min_aesthetic: 7 }

Inputs: text, limit, subject, exposure, +3 more.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 12 tools

    Disambiguation5/5

    Each tool targets a distinct step in the video editing pipeline (init, scan, analyze, search, propose, edit, render, health), with clear descriptions preventing overlap. Even similar tools like scan and analyze are clearly distinguished by their operations and outputs.

    Naming Consistency4/5

    All tools use the 'skycut_' prefix and mostly follow verb_noun pattern. Exceptions like 'skycut_health' and 'skycut_project_status' use nouns, but the overall pattern is consistent enough for easy navigation.

    Tool Count5/5

    12 tools are well-scoped for a video editing MCP server, covering the full pipeline from setup to final render without unnecessary redundancy. Each tool serves a clear purpose.

    Completeness4/5

    The tool set covers the major workflow stages (init, scan, analyze, search, propose, edit, preview, render). Minor gaps exist (e.g., no standalone clip trimming or subtitle export), but the core pipeline is complete.

    Related MCP Connectors

    Related MCP Servers