makevideo MCP server
Commit Oct 16, 2026Generates narrated, captioned MP4 videos from Markdown or JSON scripts using local CPU-only processing.
Also known as random00000000/makevideo
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 0.6.0
- Last commit
- Oct 16, 2026
- License
- MIT
What is makevideo MCP?
makevideo generates narrated, captioned MP4 videos from Markdown or JSON scripts using local CPU-only processing.
Summary generated from the project's README
About makevideo MCP server
Creating narrated, captioned MP4 videos from Markdown or JSON scripts is what makevideo enables for developers and AI agents. This MCP server allows users to transform text-based specifications into finished video files using local CPU-only processing, meaning no GPU or cloud API keys are required. It is designed to provide a consistent standard for video generation, ensuring that every render follows a predictable pipeline with synchronized audio and visual elements.
Users can interact with the server through various MCP clients like Claude Desktop, Cursor, or VS Code. The server provides specific tools including make_video for the main rendering process, preview_video to generate a contact sheet image for visual verification, and check_video to lint scripts for pacing or text density. It supports diverse formats ranging from documentary styles with Wikimedia Commons image integration to vertical shorts for social media, all while handling narration via the Kokoro-82M voice engine.
What you can do with it
- 1Generate social media shortsAn AI agent can create vertical 1080x1920 videos with large word-by-word captions for platforms like TikTok.
- 2Create software patch notesTeams can turn technical changelogs into narrated videos showing code snippets and gameplay clips.
- 3Verify video content visuallyAn agent can check a visual contact sheet to ensure the video layout looks correct before a full render.
Written from the project's README. Every use case is checked against a quote from it.
How to install makevideo MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall makevideo MCP in Claude Code
$ claude mcp add makevideo -- docker run -i --rm ghcr.io/random00000000/makevideo:0.6.0Install makevideo MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"makevideo": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/random00000000/makevideo:0.6.0"
]
}
}
}Install makevideo MCP in VS Code
.vscode/mcp.json
{
"servers": {
"makevideo": {
"type": "stdio",
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/random00000000/makevideo:0.6.0"
]
}
}
}Install makevideo MCP in VS Code CLI
$ code --add-mcp '{"name":"makevideo","type":"stdio","command":"docker","args":["run","-i","--rm","ghcr.io/random00000000/makevideo:0.6.0"]}'Install makevideo MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"makevideo": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/random00000000/makevideo:0.6.0"
]
}
}
}Install makevideo MCP in Codex
$ codex mcp add makevideo -- docker run -i --rm ghcr.io/random00000000/makevideo:0.6.0Install makevideo MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.makevideo] command = "docker" args = ["run", "-i", "--rm", "ghcr.io/random00000000/makevideo:0.6.0"]
Install makevideo MCP in Gemini CLI
$ gemini mcp add -s user makevideo docker -- run -i --rm ghcr.io/random00000000/makevideo:0.6.0Install makevideo MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"makevideo": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/random00000000/makevideo:0.6.0"
]
}
}
}Automated checks
Ran Nov 14, 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 reachablerandom00000000/makevideo is public and reachablegithub.com/random00000000/makevideo ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-16github.com/random00000000/makevideo ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubmakevideo
Fast, standard video generation for AI agents. One JSON script in, one finished MP4 out, rendered the same way every time. You write scenes, each with a line to say. makevideo voices them with one consistent neural voice, times every scene to the real audio, adds captions, and renders an MP4 with a bundled ffmpeg. It runs on the CPU only: no browser, no GPU, no API key and no cloud.
▶ Your agent can make videos now (1:39, written, voiced and rendered by an agent from one JSON file) · ▶ Watch the 87-second showcase, rendered from examples/showcase.json on a laptop CPU, faster than it plays.
Short-form too: "format": "shorts" gives 1080×1920 with big word-by-word captions. ▶ Watch the TikTok-style demo (examples/tiktok.json): 23 s of video rendered in 15 s, plus an auto-exported GIF.
More examples, all made with makevideo: ▶ What's new in 0.6: game trailers (spec) · ▶ Neon Drift game trailer (beat sheet) · ▶ What's new in 0.5: documentaries (spec) · ▶ 59-second demo (spec) · ▶ The house voice · ▶ Distribution recap · ▶ What's new in 0.4: closer to every agent (spec) · ▶ What's new in 0.3: speed (spec) · ▶ What's new in 0.2 (made from one Markdown file) · ▶ Why use makevideo instead of building from scratch (spec) · ▶ Changelog video for v0.1 (spec): changelog and recap videos are a core use case.
What it does: game trailers cut on the beat, with shots filmed from your Electron + Three.js game · narrated slides · automatic transitions (push, slide, zoom, wipe) · kinetic statements · animated charts · split media + text · write Markdown, get a video · screenshots · gameplay/video clips · GIFs in and out · code · stats · quotes · before/after · TikTok/Reels/Shorts captions · custom fonts · background music · screen recording for trailers · .srt captions · poster frames.
npm i github:random00000000/makevideo
npx makevideo init # writes video.json (or: init --style documentary | shorts | explainer)
npx makevideo video.json # → video.mp4 + video.srt + video.report.json + video.jpg
npx makevideo video.json --fast # same, about 3x faster on a first render
import { video } from 'makevideo';
await video({
title: 'Patch notes 1.2',
scenes: [
{ type: 'title', title: 'Patch 1.2', subtitle: 'Siege update', say: 'Here is what is new in patch one point two.' },
{ type: 'clip', src: 'siege.mp4', title: 'Rams breach gates', say: 'Rams can now breach wooden gates.' },
{ type: 'bullets', title: 'Also new', items: ['Faster pathing', 'New HUD'], say: 'Also new. Pathing is faster. And the HUD is redesigned.' },
{ type: 'decisions', items: ['Ship Friday?'], say: 'One decision for you. Do we ship on Friday?' },
],
});
Why
Agents get asked for videos all the time, and every agent builds them differently. Each video ends up with a new pipeline, a different voice, no narration unless someone asks for it, and a render that can take ten minutes. makevideo makes that one standard:
| ad-hoc agent videos | makevideo |
|
|---|---|---|
| Format | a new script every time | one JSON spec (schema) |
| Voice | random TTS, sometimes none | Kokoro-82M, same voice every time (af_heart) |
| Narration | must be requested | on by default: every scene has say |
| Timing | guessed | measured from the generated audio, per sentence |
| Captions | rarely | burned in, plus an .srt sidecar |
| Speed | minutes | faster than real time on a CPU (see Performance) |
| Verification | watch the whole thing | makevideo preview makes a contact sheet in about 1 s |
Premium by default
The goal is that an agent's first attempt looks finished. Without any extra config you get:
- Transitions that blend real frames. Every scene flows from the previous scene's actual last frame.
autopicks push, zoom, wipe or fade based on what is cut to what. Override with"transition"globally or per scene. - Typography that ships with the package. Inter, Montserrat and JetBrains Mono (OFL) are bundled, so a bare cloud Linux box renders exactly like your laptop.
- Depth: key-light gradient, vignette and soft panel shadows on every theme.
- Speech cleanup: write naturally.
42%,v1.2,$3M,4.6x,35 s,e.g.and->are all spoken correctly, and captions keep what you wrote. - Lint:
checkflags walls of text, too many bullets, unsynced lists, overlong statements, dense scenes in portrait and repetitive pacing, and says how to fix each one.
YouTube documentaries (history, science, dinosaurs)
One switch, style, sets the whole look and sound: documentary (history channels), history (adds a war-drum score), or nature (science and dinosaurs). Then write the script and say which images you want:
---
title: Tyrannosaurus rex, the tyrant lizard king
style: nature
thumbnailText: The real T. rex
---
## Tyrannosaurus rex
![Tyrannosaurus rex skeleton museum]()
The tyrant lizard king
> Sixty six million years ago, the largest predator in its world...
## Chapter: Built to kill
![Tyrannosaurus rex skull]()
> Chapter two. Built to kill.
## Timeline
- 68 Mya: T. rex appears
- 66 Mya: Asteroid impact
> Its story fits on one line. It appears sixty eight million years ago. It vanishes when the asteroid hits.
What you get, with no other settings:
- Image check:
previewlists which file each search picked, and flags with "?" any pick whose title doesn't match the query (for example a different species). Agents can refine the search before rendering. - Real images, licensed for publishing.
![description]()(or"search": "..."in JSON) searches Wikimedia Commons. It keeps only publish-safe licenses (CC0, public domain, CC BY, CC BY-SA), never reuses an image within a video, caches downloads, and shortens over-specific searches until something matches. Each image gets a small credit line, and the full attributions go into the description. - Cinematic motion: slow Ken Burns on every still, varied by scene (in, out, left, right, up, down; set
pan/focusto override), plus chapter cards (## Chapter: ...) and timelines. - A score: an original royalty-free music bed is synthesized for the video (
music: documentary | epic | wonder | tension) and ducked under the narration. - Broadcast loudness: the final mix is normalized to −14 LUFS, YouTube's playback target.
- A publish package:
video.thumbnail.jpg(1280×720), andvideo.description.txtwith YouTube chapter timestamps (0:00 first, each at least 10 s apart) and image credits.
▶ The T. rex example (script): 2 min 37 s, rendered from one Markdown file.
From a transcript: treat another creator's transcript as research, not as a script. Have the agent write its own narration. Republishing someone else's script is copyright infringement, and YouTube demonetizes it as "reused content".
Text on screen vs. narration (the cohesion rules)
The engine enforces these, and following them in the script makes videos land:
- The screen shows keywords; the voice says sentences. Titles, bullets and labels are short ("Faster builds"); narration is the full thought ("Builds are now twice as fast").
- Big statements use the narrator's own words. Statement words appear one by one as they are spoken, so put the same words in
say.checkwarns when they don't match. - Captions never repeat the screen. Any caption whose words are already displayed is hidden on screen automatically (the
.srtkeeps every line). Usecaptions: "all"to turn this off.
Write Markdown, get a video
---
theme: midnight
brand: My Game
---
# Patch 1.2
The siege update
> Here is what changed in patch one point two.
## Rams breach gates

- Wooden gates break in 3 hits
- Stone gates still hold
> Rams now breach wooden gates. Three hits and they are down. Stone gates still hold.
## Load time
<!-- highlight: Now -->
- Before: 12 s
- Now: 3 s
## Decisions
- Ship Friday?
npx makevideo patch-notes.md
Each #/## heading starts a scene, and its body decides the type: a list gives bullets/steps/decisions, label: number items give a chart, an image or video gives image/clip (or split, when there is text too), a code fence gives code, **42%** label gives a stat, and a paragraph gives a statement. Lines starting with > are the narration. When a scene has none, its visible text is read aloud, because narration is the default. <!-- key: value --> sets scene options. See examples/whats-new-0.2.md; the 0.2 release video is that one file.
Use it from Claude Code (plugin)
/plugin marketplace add random00000000/makevideo
/plugin install makevideo@makevideo
Then just say "make a video about …". Claude writes the spec, previews it, renders it, and hands you the MP4.
The plugin bundles both the skill and the MCP server.
Use it from any MCP client
Claude Desktop, Cursor, VS Code, Codex, Windsurf and other MCP clients:
{ "mcpServers": { "makevideo": { "command": "npx", "args": ["-y", "github:random00000000/makevideo", "mcp"] } } }
It's listed in the official MCP Registry as io.github.random00000000/makevideo, as a Docker image (ghcr.io/random00000000/makevideo). Without Node, run docker run -i --rm -v "$PWD:/work" -w /work ghcr.io/random00000000/makevideo mcp.
The tools are make_video (Markdown or JSON in, MP4 out, with progress notifications), preview_video (returns the contact sheet as an image the model can look at), check_video and video_reference. See the MCP guide.
Teach every agent in a repo
npx -y github:random00000000/makevideo agents --all # AGENTS.md, CLAUDE.md, Cursor rules, Copilot instructions
npx -y github:random00000000/makevideo agents --global # this machine: Claude Code skill + Codex AGENTS.md
This writes a short, idempotent "use makevideo for videos" block, so every agent that works in the project reaches for the same tool.
Guides: agents · CPU text-to-video · Markdown to video · TikTok/Shorts · game trailers · MCP · vs Remotion/MoviePy/ffmpeg
For AI agents (start here)
If you are an LLM agent and the user asked for a video, explainer, walkthrough, devlog, demo, trailer, recap, patch notes or presentation with voice-over, use this library:
- Write a spec: a
scenesarray where every scene has atypeand asaystring (the narration). npx makevideo check spec.json --jsonvalidates it and estimates the length (instant).npx makevideo preview spec.json: open the PNG contact sheet and check the layout (about 1 s, no audio).npx makevideo spec.json --jsonrenders and prints{ output, srt, report, poster, duration, seconds }.- Hand the user the
.mp4. End informational videos with adecisionsscene listing what only the user can decide.
Rules of thumb: about 1–3 sentences per scene. Write say the way it should be spoken: spell out numbers and symbols ("forty two percent", not "42%") and use pronounce for names. Put on-screen text in title/items; it does not have to match the narration word for word. Reuse the same voice and theme across a project so all its videos match.
There is also AGENTS.md, llms.txt, a JSON Schema at schema.json, and a drop-in Claude Code skill at skills/makevideo/SKILL.md. Copy that folder to ~/.claude/skills/ and Claude will reach for makevideo whenever you ask for a video.
Spec
{
"title": "My video", // used for default output name
"output": "out/my-video.mp4", // default: <title-slug>.mp4 (relative to spec file)
"format": "landscape", // landscape 1920x1080 | portrait/shorts 1080x1920 | square | 720p
"style": "nature", // documentary | history | nature: whole look + score + YouTube package
"theme": "midnight", // midnight | forge | paper | terminal | documentary | nature | { ...overrides }
"voice": "af_heart", // the default house voice (warm female); "fast" = ~10x real-time Piper voice (male); false = silent
"speed": 1, // speech rate
"brand": "My Project", // small label top-right
"captions": true, // burned-in captions (an .srt is always written)
"progressBar": true, // chapter bar along the bottom
"music": "documentary", // generated score: documentary | epic | wonder | tension, or a file; ducked under the voice
"musicVolume": 0.12,
"pronounce": { "Hacksilver": "Hack silver" }, // TTS-only substitutions (merged over built-ins for JSON, MP4, GPU, ...); captions keep originals
"quality": "standard", // draft | standard | high
"transition": "auto", // auto | push | slide | zoom | wipe | fade | dip | cut (also per scene)
"captionStyle": "classic", // classic (subtitle box) | bold (TikTok word-by-word, default for portrait) | none
"font": "fonts/Anton.ttf", // display font: a .ttf/.otf path or an installed family name
"gif": { "width": 480, "fps": 12, "duration": 8 }, // also export an animated GIF (true = defaults)
"scenes": [ /* see below */ ]
}
Every scene accepts say (narration) and an optional duration (minimum seconds; required if there is no say). Scenes are as long as their narration plus a short pad.
| type | fields | notes |
|---|---|---|
title |
title, subtitle?, kicker? |
opening card; outro is an alias for closers |
bullets |
title?, items[], highlight? |
items appear in sync with sentences: N items + 1 intro sentence works best |
steps |
title?, items[] |
numbered bullets |
decisions |
title?, items[] |
numbered, for "what the user must decide" |
image |
src, title?, subtitle?, fit?, zoom? |
slow push-in; fit: "contain" keeps the whole image with a blurred backdrop |
clip |
src, start?, title?, subtitle?, fit? |
any mp4/webm/mov; cropped to fill, looped if short; original audio dropped |
code |
code, title?, highlight? ([3, [5,8]]) |
syntax-tinted, line numbers |
stat |
value, label? |
numbers count up ("42%", "$1.2", "3x") |
quote |
text, by? |
|
compare |
title?, left: {title, items}, right: {title, items} |
stacks vertically in portrait |
statement |
text, kicker?, align? |
huge kinetic type; words pop in with the voice; *stars* mark accent words |
chart |
bars: [{label, value}] (or {label: value}), title?, unit?, prefix?, highlight?, note? |
bars grow as the voice reaches them; values count up |
chapter |
title, number?, subtitle?, src or search |
full-bleed image chapter card with a serif title (## Chapter: ... in Markdown) |
timeline |
events: [{when, label}], title? |
events light up as the voice reaches them (## Timeline + - When: what) |
split |
src (image or video), title?, items? or text?, side? (left/right) |
media beside synced points; video plays inside the frame |
Scene type is inferred when omitted (src + items/text → split, src → image/clip, bars → chart, items → bullets, code → code, value → stat, text → statement).
CLI
makevideo <spec.json|spec.js> render (mp4 + srt + json report + jpg poster)
makevideo check <spec> validate, estimate duration (instant)
makevideo preview <spec> contact-sheet PNG of every scene (about 1 s)
makevideo init [file] [--style trailer] starter spec / trailer beat sheet
makevideo shoot <trailer.md> [--all] [--only "Label"] film every shot from your Electron game
makevideo beats <song.mp3> tempo, beats and sections of your track
makevideo record <out.mp4> --seconds 10 [--window "Game"] record screen/window for clip scenes
makevideo agents [--all|--global] tell agents to use makevideo for videos
makevideo mcp MCP server (stdio)
makevideo setup pre-download voice models
makevideo voices | themes | types | transitions | formats
-o <file> --draft --format <f> --voice <id> --theme <name> --json
A .js spec can export default { ... } (or an async function returning the spec), which is handy for generating scenes from data.
API
import { video, check, preview, VOICES, THEMES, SCENE_TYPES } from 'makevideo';
const r = await video(spec, { baseDir, onProgress: (e) => console.log(e.stage, e.message) });
// r = { output, srt, report, poster, duration, seconds, scenes: [{ index, type, title, start, duration, say }] }
check(spec) // { ok, problems[], estimatedSeconds }
await preview(spec) // { output: '...preview.png' }
Errors are written so an agent can act on them. They name the scene and include a working example:
makevideo: invalid spec
- scenes[2] (clip) is missing "src". Example: {"type":"clip","src":"gameplay.mp4","start":2,...}
- scenes[4] has no "say" (narration) and no "duration". Narration is the default in makevideo: ...
Game trailers: shot list → filmed shots → cut on the beat
▶ Watch the Neon Drift trailer (36 s). The sample Electron + Three.js game filmed all of its own shots from one beat sheet, and every cut lands on the music.
A trailer is a shot list, the shots, and an edit on the music. makevideo does all three:
npx makevideo init --style trailer # trailer.md: a beat sheet (shots, text slams, logo, Wishlist card)
npx makevideo preview trailer.md # storyboard on the beat grid + trailer lint (about 5 s)
npx makevideo shoot trailer.md # launches your Electron game and films every shot
npx makevideo trailer.md # cuts it on the beat with a score, text, logo and end card
1. The shot list is a beat sheet. Each ## block is one beat of the edit, measured in music beats. A shot block says what to film. A lone line of text is a slam card. # is the logo. "Wishlist on Steam" is the end card.
---
style: trailer
title: Neon Drift
bpm: 110
---
## Dogfight
<!-- section: drop, beats: 4 -->
```shot
setup: |
game.reset(); game.wave(20);
camera: orbit hero 9 2 -40 40
```
FLY FAST
## Until
THEN THEY CAME
# NEON DRIFT
A neon arena shooter
## Wishlist on Steam
Coming 2027
2. The game films itself. You add two lines to the game:
// Electron main process
require('makevideo/electron').attach(win);
// renderer (your Three.js code)
window.makevideo = { renderer, scene, camera };
makevideo shoot starts the game, runs each shot's setup code, and moves the camera (orbit, push, dolly, fly, follow, hold, around any named object). It then records the canvas at 1920×1080 on virtual time, frame by frame. Footage is perfectly smooth at 30/60 fps even when your machine renders the game at 20 fps, and the HUD is never in the shot. Shots that need the game's own audio can use mode: realtime.
Instant replay: while you play, press F8 to save the last 15 seconds to makevideo-clips/, for the moments you can't script.
3. The edit is built on the music.
- Every scene lasts a whole number of beats, and every cut lands within half a frame of its beat.
- Cuts that land on a hit flash.
- The generated score follows your sections (intro → build → drop → breakdown → finale → outro), with braams, drums and risers. You can also bring your own track:
makevideo beats song.mp3finds the tempo, beats and sections, andbpm+musicOffsetmake the sync exact. - Clips play at their
speed(orramp: 1>0.3), andstart: autopicks a clip's most active window. - Each clip's game audio sits under the music, and the master is normalized to −14 LUFS.
Trailer lint applies rules from how good Steam trailers are cut:
- gameplay before 5 s
- logo after gameplay, never before it
- 30–90 s long
- end on a call to action
- text slams of 5 words or fewer
- no three text cards in a row
- clips that would loop
- shots that run past the music
Screen recordings
When the game isn't Electron, or you just want raw footage:
npx makevideo record captures/siege.mp4 --seconds 12 --window "Hacksilver" # one window (Windows)
npx makevideo record captures/menu.mp4 --seconds 8 # whole screen (Win/macOS/Linux)
Then use  in the beat sheet.
makevideo MCP questions
How do I add makevideo MCP to Claude Code?
Run claude mcp add makevideo -- docker run -i --rm ghcr.io/random00000000/makevideo:0.6.0 in your terminal. Add --scope user to make it available in every project.
How do I add makevideo MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
Does it require an API key or GPU?
No, it runs on the CPU only and does not require an API key or a GPU.
What formats can I use to create videos?
You can provide either a JSON script or a Markdown file to generate a video.
Can I use it with Claude Desktop or Cursor?
Yes, it can be used with any MCP client including Claude Desktop, Cursor, VS Code, Codex, and Windsurf.

