Reelsaw MCP server
Commit Nov 15, 2026Turn long-form videos into vertical short-form clips with AI-powered transcription, smart reframing, and automated captioning.
Also known as osbytes/reelsaw
- Stars
- 12
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 0.39.0
- Last commit
- Nov 15, 2026
- License
- AGPL-3.0
What is Reelsaw MCP?
Reelsaw turns long-form videos into vertical short-form clips with AI-powered transcription, smart reframing, and automated captioning.
Summary generated from the project's README
About Reelsaw MCP server
Content creators and video editors can transform long-form videos into vertical short-form clips using Reelsaw. By providing a YouTube link or uploading a video file, the system uses AI to transcribe the audio, identify the most engaging moments, and render 9:16 clips complete with automated captions and smart reframing. It is designed for self-hosting via Docker Compose or through a hosted service.
The server is highly flexible, supporting any AI vendor through the AI SDK, including OpenAI, Anthropic, Google, and Groq. It can even run fully locally without API keys using providers like Ollama or local Whisper servers. The pipeline handles everything from initial ingestion and transcription to a sophisticated pairwise ranking process that selects the best clips based on a rubric of hook, value, flow, and shareability.
Beyond simple clipping, the tool provides advanced editing features like smart reframing that detects faces or stacks speakers, and a multi-lane timeline for frame-accurate trims. Developers can manage assets through a command palette or via specific MCP commands to list, restore, or purge projects and clips.
What you can do with it
- 1AI-driven moment selectionUse a research-backed ranking system to find the most shareable segments of a transcript.
Written from the project's README. Every use case is checked against a quote from it.
How to install Reelsaw MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Reelsaw MCP in Claude Code
$ claude mcp add reelsaw -- docker run -i --rm ghcr.io/osbytes/reelsaw:0.39.0Install Reelsaw MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"reelsaw": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/osbytes/reelsaw:0.39.0"
]
}
}
}Install Reelsaw MCP in VS Code
.vscode/mcp.json
{
"servers": {
"reelsaw": {
"type": "stdio",
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/osbytes/reelsaw:0.39.0"
]
}
}
}Install Reelsaw MCP in VS Code CLI
$ code --add-mcp '{"name":"reelsaw","type":"stdio","command":"docker","args":["run","-i","--rm","ghcr.io/osbytes/reelsaw:0.39.0"]}'Install Reelsaw MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"reelsaw": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/osbytes/reelsaw:0.39.0"
]
}
}
}Install Reelsaw MCP in Codex
$ codex mcp add reelsaw -- docker run -i --rm ghcr.io/osbytes/reelsaw:0.39.0Install Reelsaw MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.reelsaw] command = "docker" args = ["run", "-i", "--rm", "ghcr.io/osbytes/reelsaw:0.39.0"]
Install Reelsaw MCP in Gemini CLI
$ gemini mcp add -s user reelsaw docker -- run -i --rm ghcr.io/osbytes/reelsaw:0.39.0Install Reelsaw MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"reelsaw": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/osbytes/reelsaw:0.39.0"
]
}
}
}Configuration
AI_MODELCOMPOSE_FILEOPENAI_API_KEYOPENAI_BASE_URLOPENAI_COMPATIBLE_API_KEYOPENAI_COMPATIBLE_BASE_URLOTEL_ENABLEDOTEL_EXPORTER_OTLP_ENDPOINTOTEL_SERVICE_NAMESPEACHES_IMAGETRANSCRIPTION_MODELWHISPER_MODEL
| Name | Description | |
|---|---|---|
| AI_MODEL | — | |
| COMPOSE_FILE | — | |
| OPENAI_API_KEY | — | |
| OPENAI_BASE_URL | — | |
| OPENAI_COMPATIBLE_API_KEY | — | |
| OPENAI_COMPATIBLE_BASE_URL | — | |
| OTEL_ENABLED | — | |
| OTEL_EXPORTER_OTLP_ENDPOINT | — | |
| OTEL_SERVICE_NAME | — | |
| SPEACHES_IMAGE | — | |
| TRANSCRIPTION_MODEL | — | |
| WHISPER_MODEL | — |
Automated checks
Ran Nov 13, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packageNot checked
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesNot checked
README
View on GitHubSelf-hosted, AI-powered long-form → short-form video clipper. Paste a YouTube link or upload a video; Reelsaw transcribes it, asks an LLM for the most clippable moments, then renders vertical 9:16 clips with word-highlight captions and a hook overlay. A hosted service at app.reelsaw.com runs the same code (Free, then $12 / $29 / $59 a month, metered in source minutes).
Pure TypeScript. Any AI vendor via the AI SDK. One-step deploy with Docker Compose.
Features
Pipeline
- Any AI vendor – language model, transcription model and caption-alignment model are each a
provider:modelstring: OpenAI, Anthropic, Google, Groq, Deepgram, AssemblyAI, Vercel AI Gateway, or any OpenAI-compatible server (Ollama, vLLM, LM Studio, local Whisper servers). Fully local with no API keys is supported. - Research-backed clip selection – map → pool → rank: the transcript is chunked at long pauses with 20% overlap (no "lost in the middle" on long videos), every standalone moment is collected per chunk in parallel, candidates are snapped/deduped, then scored on a rubric (hook / value / flow / shareability, plus relevance with a focus) as the median of k samples, and the top 10 get K sliding pairwise head-to-head passes (PRP-Sliding-K;
ANALYZE_PAIRWISE_PASSES, default 3 so the top 3 you see first are placed reliably) with positions swapped to cancel judge bias. Cost: at most Σ(n−1−p) pairs × 2 calls, i.e. 48 calls for the top 10 with 3 passes (18 with 1); pairs met twice are judged once. No target count: in auto mode weak picks are dropped by a gate relative to the run, not a fixed number, because pointwise scores do not transfer between judge models: a clip is dropped below max(ANALYZE_MIN_SCORE_FLOOR= 25, median −ANALYZE_SCORE_MAD_K= 1 × MAD) of the pooled rubric totals, and the best clip is always kept (ANALYZE_SCORE_RULE=absoluterestores the old fixed 45). The threshold and its median/MAD are in the project'scandidatesartifact. Candidates whose scoring failed are never compared with rubric totals; they only fill in when fewer than 3 scored clips survive. Optional "at most N" cap, and "Find clips about …" keeps only on-topic moments. Click a clip's score for the breakdown.ANALYZE_JUDGE_MODELlets a different model score and compare (less self-preference than judging its own hooks).ANALYZE_CONCURRENCY,ANALYZE_SCORE_SAMPLES,ANALYZE_PAIRWISEtune cost (auto: 1 call at a time, 1 sample, no pairwise for a self-hosted judge; 4 / 3 / on for cloud). - Clean transcripts – names are fixed from vocabulary hints and a constrained LLM correction, and fillers, repetitions and false starts are cut with jump cuts. Every cut is located by forced alignment and checked by listening to the seam, so karaoke highlights land on the syllable. Each fix shows inline in the transcript with accept/reject, and long pauses can be shortened (details below).
- Smart 9:16 reframing – UltraFace (1.2 MB ONNX, CPU, ~7 ms/frame via
onnxruntime-node) samples each clip at 4 fps and picks a layout per segment (clips are split at scene cuts and face-presence changes, so a picture-in-picture intro can be "fit" and the talking head after it "face"; shot cuts are detected on every clip, and a multi-camera edit that alternates a close-up with a wide shot every second or two changes layout at each cut): face (crop follows the speaker with "heavy tripod" smoothing: dead zone, capped pan speed, instant snap at scene cuts), split (two speakers stacked), stack (slides/screen on top, the webcam tile below — the picture-in-picture box of a Zoom, Teams, Meet or OBS recording, not a face-sized crop that reaches into the slides), or fit (whole frame over a blurred background when there is no face, e.g. graphics and b-roll, or when three or more people share the frame). With two people in a wide shot the crop follows whoever is talking (mouth motion correlated with the audio envelope, minimum 2.5 s per shot), falling back to a split when detection isn't confident. Override per project, per clip or per section, including a hand-set crop. Reference for every layout, its triggers, caveats and fixtures: docs/LAYOUTS.md. - Captions – AI-picked key words per clip coloured and enlarged (editable in the editor), readability limits (≈2 short lines, comma/sentence breaks, a line stays up long enough to read: at least 0.7 s, 0.3 s per word and 20 characters per second), ASS karaoke word highlight (any colour), boxed, or outlined; size, words on screen (1 = one word at a time), uppercase; hook overlay with its own duration. Caption and hook positions are free x/y set by dragging on a live 9:16 preview that uses the renderer's crop math and font metrics, with a platform safe-zone overlay. In split and stack sections that last 2.5 s or more, captions sit on the line between the two panes instead of on the lower speaker (a switch turns it off). Project-wide defaults, per-clip overrides. Burned in with ffmpeg + libass.
Editing
- Workspace and clip editor – source player and clickable transcript on the left, clips streaming in on the right as they render, with score, layout badge, post caption + hashtags copy and download. The editor has a live preview of the source with the clip's framing and captions and a multi-lane timeline (ruler, transcript words, clip range, layout track, layers) with zoom, snapping to words/scene cuts/playhead, nudge buttons, typed timestamps and I/O keys for frame-accurate trims. Split the layout track (⌘/Ctrl+B, the Split button, a double-click or the right-click menu) into sections that are Auto or forced to face/split/stack/fit/centre; drag the picture to re-centre a section; right-click for Set crop… (a box on the source, or
crop/crop2/contentCroponupdate_clip); "Use for all clips…" copies one clip's framing to the project (apply_framing). Add, drag and remove transitions; ⌘/Ctrl+Z / ⇧⌘Z undo and redo every edit. - Deletes can be undone – deleting a project or a clip (card ⋯, the selection bar, the editor, ⌘K) stops its work and hides it. The toast always offers Undo, Delete forever, and See deletions. Everything restorable lives on Deleted (account menu) as one selectable list: each row says when it was deleted and when it is deleted forever, and a compact bar restores the selection or deletes it forever. Storage still counts until you delete it forever (MCP
list_deletedpluspurge_project/purge_clip/purge_asset/purge_layer_template;reelsaw purge-project,purge-clip,library purge,templates purge). Minutes, hourly creates and first-video-free are never refunded. Re-picking moments keeps every clip you made or edited (text, bounds, framing, style, intro/outro) and only replaces untouched AI picks, which can be restored too. The same through MCP (delete_clip,delete_clips,restore_project,restore_clip,list_deleted) and the CLI (reelsaw deleted,restore,delete-clip,delete-clips,restore-clip,purge,purge-project,purge-clip). - Learns from your decisions – what you accept, reject, cut, correct and edit is kept in a decision log (with the words or clip text it was about, the models that proposed it and a fingerprint of the source video) that outlives deleted projects: cuts you rejected are shown to the filler detector as examples to keep, and an export turns your decisions into eval cases (
reelsaw decisions export,export_decisions, thedecisionssuite). Settings → Learning turns it off or forgets everything; deleting a project (or "Delete forever") can forget what it learned from that project, applied when it is purged, even automatically. It never leaves your instance. See docs/specs/decision-log.md. - Command palette and bulk export – ⌘K searches projects and clips with status, length and age, opens a row's actions (open, export, resume, retry failed clips, re-run refine, re-render, download, delete project or clip), takes pasted links (one project each, or opens the existing one) and offers retry-all shortcuts. "Export all" zips every rendered clip with platform-ready metadata: a paste-ready
.txt(title, description, tags, caption), a.youtube.json(YouTube Data API v3videos.insertbody, private by default) and a.tiktok.json(Content Posting APIpost_info,SELF_ONLY) per clip, plusmanifest.json,clips.csv(with rendered duration) and a README. Descriptions carry a timestamped link to the exact moment in the parent video. - Share links – a clip's ⋯ menu copies a link anyone can download it from without signing in (the project and selection menus do the same for the zip), for schedulers (Buffer, Metricool), Instagram's
video_url, Zapier/Make file fields or a person. The link answers with the file itself (a plain 200, no redirect), serves the clip's latest render, lasts 90 days by default (MEDIA_LINK_TTL_DAYS; "Never" whereMEDIA_LINK_ALLOW_NEVER), and can be revoked one at a time, per clip or project, or all at once under Settings → Share links. MCPget_media_links,list_media_links,revoke_media_link;reelsaw media-links. See docs/specs/media-links.md. - Webhooks – Settings → Webhooks sends signed JSON (Standard Webhooks:
webhook-id,webhook-timestamp,webhook-signature) to your URLs onproject.created,project.done(every clip with share links and the zip),project.failed,clip.doneandclip.failed, so n8n, Zapier, Make or a script can act the moment clips are ready instead of polling. Deliveries commit with the event, are retried 8 times over about 22 hours, and an endpoint that fails for 3 days is turned off with an email; each has a delivery log with the request, the answer and Resend. A project'smetadata(create_project) comes back in every webhook for it. MCPcreate_webhook/delete_webhook(how a Zapier or Make app subscribes),list_webhooks,update_webhook,rotate_webhook_secret,test_webhook,list_webhook_deliveries,resend_webhook_delivery;reelsaw webhooks. See docs/specs/webhooks.md. - SRT / VTT in and out – every rendered clip's ⋯ menu offers its captions as
.srtor.vtt(the same lines and times as the video, intro included, even when the style has captions off), and "Export all" adds them next to each clip asclips/NN-title.srtand.vtt; clips rendered before this feature need a re-render first. The project's ⋯ menu ("Transcript files…") downloads the transcript the same way (VTT can carry a timestamp before every word) and imports a subtitle file you already have: right after creating a project (only the video is fetched) or on a done or failed one (it cleans the transcript up and picks clips again). Imported cues become segments and their words are spread over the cue by length; the render re-aligns words to the audio. AlsoGET /api/clips/:id/captions.srt|vtt,GET /api/projects/:id/transcript.srt|vtt(?words=1for VTT word times), the MCP toolsget_clip_captions,get_project_transcript_fileandimport_transcript, andreelsaw captions,transcript-fileandimport-transcript.
Library, layers and templates
- Library – intros and outros, logos, stickers, b-roll, music and sound effects (PNG, JPG, GIF, WebP, SVG, video, audio). Drop many files at once (duplicates are detected), search your items plus a bundled catalog and, with an admin key, Pexels, Pixabay, Freesound, Iconify, Giphy and Klipy. Each clip is rendered as intro + clip + outro in a single encode, fitted to vertical over a blurred background.
- Per project and per clip – a project follows the default intro/outro, uses none or a specific item; each clip can follow the project, use none or pick its own. An unusable asset is skipped with a plain-language event instead of failing the clip.
- Layers – one timeline lane for image/video overlays, text and sound (
update_clip { layers },reelsaw clip-layers): position, size, opacity, fade in / out, fonts shipped in the image, several music tracks with fade, loop and sidechain ducking under speech. Right-click a layer on the 9:16 preview to edit, centre, reorder, copy or remove; double-click text to retype it. ⌘C / ⌘V copy and paste layers. - Fades and transitions – fade the clip in from black and out to black (picture and sound), and join the intro and outro with a cut, a dip to black or a crossfade; previewed live in the editor's Style tab, per clip or for every clip, and in Project defaults. Over MCP and the CLI they are style fields (
fadeIn,fadeOut,bumperTransition,bumperTransitionSeconupdate_clip { style },update_project_style,reelsaw update-style --set); a picture or text layer takesfade. See docs/specs/transitions.md. - Layer templates – save a look once (a logo pop in the first seconds, a follow card at the end, a watermark or a music bed, plus an intro and outro) with timing from the start, the end, the whole clip or a share of its length, then apply it to selected clips or set it on a project so every new clip gets it (
list_layer_templates,apply_layer_template,reelsaw templates).
Agents and automation
- MCP server –
/api/mcp(Streamable HTTP) lets Claude Code, Claude Desktop, Cursor or a script create projects, wait for them, read timed transcripts, edit layers and framing, create and re-render clips, manage the library and layer templates, and export the results. On a hosted plan the same tools are available, including Free. Authenticate with an API key from Settings, or withMCP_OAUTH=trueso claude.ai and Claude Desktop connectors sign in through the browser. - Operator CLI –
docker compose exec app reelsaw …inspects and fixes a running instance:status,events,clip,rerender,stuck,recover,logs,cuts,align,hear,flags,storage,retention,deleted,restore,purge,users,users-bulk,approve,make-admin,set-password,library,templates,apply-framing,import-reportand more (every command is in Operator CLI).
Hosting and accounts
- Accounts, approval and quotas – the first account is the admin;
SIGNUP_MODE=open|approval|closeddecides who gets in, and admins approve, suspend, promote and remove people on the Users page, with usage per account (projects, source minutes, clips, model calls and tokens, stored bytes). Optional per-user quotas, retention of old files, captcha on sign-in, email (approval notices, password reset, verification, and a note when clips finish if you've stepped away) and terms/privacy links. Everyone has their own Project defaults (vocabulary, instructions, language, clip length, pauses, caption style, intro and outro) and API keys. - Models and providers at runtime – admins switch the language, transcription and alignment models under Settings → System → Models without a restart: pick a provider, enter its key or server URL there (stored encrypted, never shown again), and choose from live model lists; local Ollama and Speaches models download with a progress bar. Keys and models are tested when saved.
Operations
- Reliable, resumable, scalable – every stage is a pg-boss job in Postgres that checkpoints its output, so a crashed or restarted worker picks up where it left off; a worker that stops heartbeating (every 15 s) has its job re-queued by pg-boss within about a minute or two, and a reconciler re-enqueues anything orphaned. A long stage saves its parts as they finish (each 3-minute window of Finding moments), so a retry or a timeout on a slow local model continues where it stopped instead of starting over, and a timeout says how far it got (
LLM_CALL_TIMEOUT_SECONDS,STAGE_IDLE_TIMEOUT_MINUTES). Run extraworkercontainers to scale. Every run (first pass, retry, re-render, re-analyze) is recorded with its own timings, and the UI shows elapsed against expected time per stage, learned from your finished projects. The browser gets live updates over a tRPC SSE subscription with automatic reconnect. - Storage and install – local volume or
s3(AWS S3, MinIO, Cloudflare R2, Backblaze B2…); superseded renders, expired sources and orphaned files are swept hourly (reelsaw storagereports,reelsaw storage sweepruns it). One-line installers for macOS/Linux (bash) and Windows (PowerShell), and Report an issue saves a zip of a project's data, decisions and logs, with secrets left out. - Observable and fail-fast – every service is built in
mainand self-checks, so the process exits with a readable reason if a model id is wrong, a key is missing, a binary is absent, the bucket is unreachable or the DB is down.LLM_TRACE=logsorlangfusecaptures every prompt/response (tokens, latency, project/clip/stage), andOTEL_ENABLED=trueturns on OTLP traces and metrics for HTTP, Postgres, pg-boss jobs, AI SDK calls (model, tokens and prompt version per call; never the prompt), ffmpeg/yt-dlp and each stage, with stage, download and transcription time per second of video and per-proxy download health.
Contributing
See CONTRIBUTING.md (principles, tests, sign-off). Roadmap for learning from user decisions: docs/SELF-IMPROVEMENT.md.
Read docs/PRINCIPLES.md first: the consistency, concurrency and UI rules every change follows. Overlay stacking (Select inside a Dialog, z-index, portals) and the mobile viewport (h-dvh, not h-screen) are docs/UI.md. Agent instructions live in AGENTS.md (the only agent file; see the process principles).
Install (no source needed)
Needs Docker (Docker Desktop on macOS and Windows). One command: it looks at the machine (RAM, GPU, Docker's memory, free disk, an Ollama already running and the models it has, the port), proposes a setup, asks three questions in a terminal (local Ollama or a hosted provider, which model, go ahead) and installs Ollama for you (Homebrew, ollama.com or winget) if you pick local and it is missing:
curl -fsSL https://raw.githubusercontent.com/osbytes/reelsaw/main/deploy/install.sh | bash
On Windows (Docker Desktop), in PowerShell:
irm https://raw.githubusercontent.com/osbytes/reelsaw/main/deploy/install.ps1 | iex
WSL2 users can run the bash one-liner as is (with Docker Desktop's WSL integration on).
It writes ~/reelsaw (compose file + .env with generated secrets), pulls the published image and
the model, starts everything and waits until http://localhost:3000 answers (or the next free port).
Fully local is the default when the machine can carry a useful model: qwen2.5:14b (~9 GB) with
24 GB of RAM or a 12 GB GPU, qwen2.5:7b from 12 GB, gemma3:4b below that, and a good model that
Ollama already has is reused instead of downloaded; with an NVIDIA GPU and the container toolkit,
Ollama and Speaches run on the GPU (and renders encode with NVENC; see "Using a GPU" below). Hosted
providers (OpenAI, Anthropic, Google, Groq, Vercel AI Gateway) are a choice in the same prompt: the
key is asked for and never echoed, and Anthropic and Google pair with local Speaches for
speech-to-text. Without a terminal, or with REELSAW_YES=1, the proposed answers are taken;
REELSAW_AI, REELSAW_LLM, REELSAW_PORT and friends answer in advance and REELSAW_DRY_RUN=1
prints the plan and stops (every option is listed at the top of the script).
Manual setup: deploy/README.md.
The scripts are deploy/install.sh and deploy/install.ps1;
they are served from main (see docs/RELEASING.md).
Quick start (from source)
git clone <this repo> reelsaw && cd reelsaw
cp .env.example .env
Reelsaw MCP questions
How do I add Reelsaw MCP to Claude Code?
Run claude mcp add reelsaw -- docker run -i --rm ghcr.io/osbytes/reelsaw:0.39.0 in your terminal. Add --scope user to make it available in every project.
How do I add Reelsaw MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
How does the smart reframing work?
It uses UltraFace to sample clips and automatically selects layouts like face-tracking, split-screen, stack, or fit based on the scene content.
Can I deploy Reelsaw myself?
Yes, it is a self-hosted solution that can be deployed in one step using Docker Compose.
Does it support local AI processing?
Yes, it supports fully local operation with no API keys required using compatible local servers.