Skip to main content
Glama

NookCut

Raw recording in, finished short out. It runs fully offline and works with any AI agent.

CI License: MIT Python 3.10+ MCP

NookCut turns a long recording (gameplay, a talk, a match, a tutorial) into a short-form video for YouTube Shorts, TikTok and Reels. It finds the moments that matter, cuts them into a story, composes original copyright-free music synced to the cuts, burns in captions, renders vertical/square/wide video, exports an editable DaVinci Resolve timeline (free edition included), and writes a publish kit with titles, hashtags and region-aware posting times.

  • Offline by design. No cloud services, no API keys, no accounts. Python's standard library and ffmpeg are all it needs. It never uploads or posts anything.

  • Works with any agent. It's an MCP server, so Claude, ChatGPT, Codex, Gemini CLI, Cursor, VS Code Copilot, local models through an MCP client, and more can drive it. Small local models can make a whole video with a single auto_edit call.

  • Online is optional. If you allow it, your agent can research trends with its own web search to sharpen hooks and hashtags. Nothing depends on it.

Status: alpha (0.1). It works end to end and is tested on macOS and Linux. Expect rough edges, and please report them.

Contents

Related MCP server: retention

Quick start

pipx install "nookcut[mcp] @ git+https://github.com/nookverse/nookcut.git"
nookcut check                      # checks ffmpeg and tells you how to fix anything missing
nookcut make ./my-short --source ~/Videos/raw.mp4 --title "Final boss, first clear" --max 45s

You get an .mp4 named after your title in ./my-short/, a publish_kit.md, and a resolve/ folder you can open in DaVinci Resolve. To let an agent do it, see Connect an agent.

Requirements

  • Python 3.10+

  • ffmpeg and ffprobe with libx264, drawtext, minterpolate, gblur and loudnorm. Most builds include them. nookcut check tells you what's missing and how to install it:

    • macOS: brew install ffmpeg-full, then put it on your PATH (it's keg-only): echo 'export PATH="$(brew --prefix ffmpeg-full)/bin:$PATH"' >> ~/.zprofile. Homebrew's plain ffmpeg is a minimal build without drawtext, so captions wouldn't work.

    • Windows: winget install Gyan.FFmpeg

    • Debian/Ubuntu: sudo apt install ffmpeg

  • A bold font for captions. Impact is found automatically on macOS and Windows; elsewhere, set NOOKCUT_FONT to any bold .ttf.

  • Optional: a GPU. NookCut encodes on NVIDIA (NVENC), AMD (AMF / VA-API), Intel (Quick Sync / VA-API) or Apple (VideoToolbox) when one works, and falls back to the CPU otherwise.

Platform

Status

macOS

Supported and tested (CI + daily use)

Linux

Supported and tested in CI

Windows

CLI and MCP server should work but aren't tested in CI yet; nookcut service is macOS/Linux only

Install

# From GitHub (until the PyPI release)
pipx install "nookcut[mcp] @ git+https://github.com/nookverse/nookcut.git"

# Or run without installing
uvx --from "nookcut[mcp] @ git+https://github.com/nookverse/nookcut.git" nookcut-mcp

# From source
git clone https://github.com/nookverse/nookcut.git && cd nookcut
python3 -m venv .venv && .venv/bin/pip install -e ".[mcp]"

The [mcp] extra installs the MCP SDK for the server. The CLI alone needs no third-party packages. Check it worked with nookcut --version and nookcut check.

Update and uninstall

pipx upgrade nookcut               # or: pipx install --force "nookcut[mcp] @ git+https://github.com/nookverse/nookcut.git"
nookcut service restart            # only if you use the shared server

To remove everything NookCut set up:

nookcut service uninstall          # if you installed the shared server
claude mcp remove nookcut -s user  # or remove "nookcut" from your agent's MCP config
pipx uninstall nookcut
rm -rf ~/.config/nookcut ~/.nookcut ~/.claude/skills/nookcut-editor

Your project folders (videos, publish kits) are yours; delete them by hand if you want.

Connect an agent

nookcut setup claude-code          # prints the exact command or config for your machine
nookcut setup all                  # every supported platform
nookcut skill install claude       # installs the editing playbook as a skill (also: codex | agents)
nookcut skill export cursor --dir ./my-project   # agents-md | gemini | cursor | windsurf | copilot | cline

For example, with Claude Code:

claude mcp add nookcut --scope user -- nookcut-mcp

Gemini CLI can install it as an extension: gemini extensions install https://github.com/nookverse/nookcut.

See docs/PLATFORMS.md for copy-paste setup for Claude Desktop, Cursor, Windsurf, VS Code, Cline, Codex, Zed, Goose, OpenAI Agents SDK, LangChain, ChatGPT and n8n.

Then ask your agent something like "Make a 45-second vertical short from ~/Videos/raw.mp4. It's my first clear of the final boss." The server also ships the editing playbook as the nookcut-editor prompt and the nookcut://skill resource, so agents without a skills system still get it.

Use it from the command line

nookcut make PROJECT --source raw.mp4 --title "..." [--game "..."] [--type gameplay|talking|sports|tutorial|generic]
             [--orientation vertical|square|wide] [--max 60] [--region "United States"] [--language en]
             [--platforms youtube_shorts,tiktok,instagram_reels] [--music ai|none|file] [--music-file song.mp3]
             [--source-audio keep|duck|mute] [--template comeback|victory|highlights] [--name file-name] [--online]
nookcut when India                 # posting windows in your own time zone
nookcut copy show PROJECT          # other caption, title and hashtag options
nookcut watch PROJECT              # live progress of any job on that project, even one your agent started
nookcut cancel PROJECT             # stop it and free the CPU at once

Step by step: new → analyze → plan → (edit edit.json) → preview → music → render → resolve. Inputs are forgiving: --orientation 9:16, --max 1:30 and --platforms shorts,reels all work.

Exit codes: 0 ok, 1 error, 2 environment missing, 3 project busy, 130 cancelled.

MCP tools

Tool

What it does

check_environment

Checks ffmpeg, filters, encoders and fonts; shows the install command if anything is missing

auto_edit

The whole video in one call: analyze, plan, captions, music, render, Resolve files and publish kit

create_project

Saves the brief (title, type, length, orientation, region, music, online opt-in)

analyze_video

Finds deaths, the win, action peaks and silent audio

plan_edit

Builds the edit from a story template with built-in captions

suggest_copy

Offline caption options per segment, plus titles, description, hashtags and a file name

get_edit / update_edit

Read or change segments and captions

preview_plan

A contact sheet image of every segment for approval

generate_music

Composes the original score (or masters your own track)

render_video

Renders the final video

export_resolve

EDLs and a Lua script that rebuild the edit in DaVinci Resolve

best_posting_times

Estimated posting windows for a region, in your time zone

write_publish_kit

publish_kit.md with titles, description, hashtags and posting plan

job_status / cancel_job

Progress (percent, stage, ETA) and instant cancel for long jobs

Long tools accept wait=false and return a job id, so clients with short tool timeouts still work. Every result includes a next hint, so even small models know what to call next.

What a project folder contains

my-short/
  brief.json         what you asked for
  analysis.json      detected moments
  edit.json          the edit: segments, speeds, captions (safe to edit by hand)
  preview.png        contact sheet for approval
  music.wav          the original score
  <name>.mp4         the finished video
  resolve/           EDLs per frame rate, markers and build_timeline.lua
  publish_kit.md     titles, description, hashtags, posting plan

Your source file is never modified.

Captions in other languages

English captions, titles and hashtags ship built in. For another language, create a pack and translate it:

nookcut copy init bn               # writes ~/.nookcut/copy/bn.json, a copy of the English pack

Translate the values (keep the keys and {slots}), then set the project's language to bn. Keys you leave out fall back to English. Packs are plain JSON, so they work offline too.

Configuration

Variable

Default

Purpose

NOOKCUT_FONT

auto

Bold .ttf/.otf for captions

NOOKCUT_ENCODER

auto

Force cpu, nvenc, amf, qsv, vaapi or videotoolbox

NOOKCUT_WORKERS

half your cores, max 4

Segments rendered in parallel

NOOKCUT_NICE

10

ffmpeg priority (0 turns lowering off)

NOOKCUT_ALLOWED_DIRS

unrestricted

Folders the MCP tools may read and write (:-separated; ; on Windows)

NOOKCUT_COPY_DIR

~/.nookcut/copy

Where your language packs live

NOOKCUT_TOKEN / NOOKCUT_TOKEN_FILE

none

Bearer token for the HTTP transport

NOOKCUT_TRANSPORT / NOOKCUT_HOST / NOOKCUT_PORT

stdio / 127.0.0.1 / 8765

Server transport settings

Running it as a shared or remote server

One shared server for every agent session on your computer (optional):

nookcut service install            # starts at login (macOS launchd / Linux systemd --user)
nookcut service connect            # prints the command that connects Claude Code to it
nookcut service status | restart | uninstall

It listens on 127.0.0.1:8765 only and requires a token stored in ~/.config/nookcut/token (readable only by you). In this mode a job keeps running if the agent session closes; stop it with cancel_job or nookcut cancel PROJECT.

Remote (ChatGPT, n8n, web agents):

NOOKCUT_TOKEN=<long-random-string> NOOKCUT_ALLOWED_DIRS=/srv/media nookcut-mcp --transport http --host 0.0.0.0
# or with Docker (ffmpeg and a font included; experimental, the image isn't tested in CI yet)
docker build -t nookcut . && docker run -p 8765:8765 -e NOOKCUT_TOKEN=<long-random-string> -v /srv/media:/media nookcut

Clients connect to http://host:8765/mcp with Authorization: Bearer <token>. The server refuses to listen off-localhost without a token. Put it behind HTTPS (a reverse proxy) before exposing it to the internet.

How it works

  1. Detection, no ML. The video is decoded at 2 fps to 64×36 pixels and measured: brightness, a red vignette at the screen edges, motion and loudness. A fade to black after a red damage vignette is a death; the first long fade after the last death is the win; motion and loudness peaks are highlights. Thresholds live in analyze.DEFAULTS.

  2. Story templates.

    • comeback: hook → death montage with a counter → "ATTEMPT #N" → best moments → slow-mo finisher → question

    • victory: a win without deaths

    • highlights: any video, top moments in order

    Each template is fitted to your length limit.

  3. Copy. Captions, titles, descriptions and hashtags come from a built-in library, filled with facts from your brief and the analysis (death count, game name, length) and wrapped to fit the screen.

  4. Music. A score is synthesized from scratch (taiko, pulse or cinematic), with hits on the cuts, then mastered. It uses no samples or existing recordings, so there's no source track to match.

  5. Render. Segments render in parallel on your GPU when possible, then they're joined and mixed with the music. The original audio is ducked under it.

Privacy and security

  • NookCut makes no network calls. Analysis, music and rendering all happen on your computer.

  • It never uploads or posts. You get files and a publish kit.

  • The HTTP server binds to localhost by default, needs a token anywhere else, and can be fenced into specific folders with NOOKCUT_ALLOWED_DIRS.

  • ffmpeg runs at lower priority and every job can be cancelled instantly.

Report vulnerabilities privately; see SECURITY.md.

FAQ

See docs/FAQ.md. Short answers:

  • Does it need the internet? No. Every step works offline.

  • Do I need an API key or subscription? No.

  • Will the music get copyright claims? It's synthesized from scratch for each video, with no samples, so there's no existing track to match. Automated systems can still misfire now and then; if one does, you can dispute it. If you use your own track, you need the rights to it.

  • Does it only work for games? No. Detection is best tuned for action games, and other videos use the highlights template.

Contributing

Contributions are welcome. Read CONTRIBUTING.md and the Code of Conduct. Notes for AI coding agents working on this repo are in AGENTS.md. Release notes are in CHANGELOG.md.

License

MIT © 2026 Nookverse

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
      D
      maintenance
      Enables AI agents to autonomously edit videos into publish-ready vertical short-form content, including silence removal, subtitle generation, voiceover synthesis, color grading, and composite pipeline creation.
      MIT
    • 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
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables users to turn raw clips into finished, beat-synced montage videos through natural-language chat, including shot selection, music matching, subtitles, transitions, and picture-in-picture. It lets agents analyze footage, plan and review cuts before rendering, and export final edits without a GPU or timeline editor.
      -