How to Use Short Video Maker: Setup, MCP, and the Limits Nobody Lists (2026)

If you want a machine that turns a block of text into a captioned vertical video, on your own hardware, for free, short-video-maker is one of the few open source projects that actually ships the whole pipeline instead of a demo notebook. It is MIT licensed, it runs in one Docker command, and it speaks MCP, so an agent like Claude Code or Cursor can operate it directly.

This guide covers the install paths, every environment variable, the MCP wiring, and the part most tool roundups skip: the limits the project itself documents, and who those limits rule out.

A note on sourcing. Every command, tag, variable, and endpoint below comes from the project's own README and Docker Hub page, linked at the end. We have not run the full generation loop on our own hardware, because that requires your own Pexels key. Where we add judgement rather than fact, we say so.

What it actually is under the hood

Four open source pieces, wired into one service:

• Kokoro.js v1.2.0 for text to speech
• Whisper.cpp v1.5.5 for the caption timing
• Pexels API for background footage
• Remotion v4.0.286 plus FFmpeg for rendering

You give it text. It narrates it, transcribes the narration to get word timings, pulls stock clips, burns captions, and renders a vertical video. Nothing in that chain calls a paid video model, which is why it can run free on a laptop.

Install path 1: Docker

This is the path the README recommends, and the one to start with:

docker run -it --rm --name short-video-maker -p 3123:3123 \
  -e LOG_LEVEL=debug -e PEXELS_API_KEY=your_key \
  gyoridavid/short-video-maker:latest-tiny

Docker Compose, if you would rather keep the rendered files:

version: "3"
services:
  short-video-maker:
    image: gyoridavid/short-video-maker:latest-tiny
    environment:
      - LOG_LEVEL=debug
      - PEXELS_API_KEY=your_key
    ports:
      - "3123:3123"
    volumes:
      - ./videos:/app/data/videos

The volume line is the one to not skip. Without it, every video you render lives inside the container and disappears with it.

Which tag to pull

Three images, and the difference is model size, not features:

Tag	Whisper model	TTS precision	Fits on
latest-tiny	tiny.en	q4 quantized	3GB RAM minimum, 4GB comfortable
latest	base.en	fp32	more RAM, better caption accuracy
latest-cuda	medium.en on GPU	fp32	Nvidia GPU box

Start on latest-tiny even if your machine is bigger. If the captions come out wrong on your material, that is the signal to move up a tag, and you will have learned something about your material rather than guessed.

Install path 2: npm

For Ubuntu 22.04 or later, or macOS. The system packages first:

git, wget, cmake, ffmpeg, curl, make, libsdl2-dev. On macOS, brew install ffmpeg plus Node.js 22 or newer.

Then clone, install with pnpm, copy .env.example to .env, fill in the variables, and start the dev server. The cmake and libsdl2-dev requirements are there because Whisper.cpp compiles locally; if your install dies partway, that is almost always where.

Windows is not supported. The README says so directly. Docker or WSL2 is the way in.

Every environment variable

One is required:

• PEXELS_API_KEY: free key from pexels.com/api. Background footage comes from Pexels, so nothing renders without it.

Worth setting:

• LOG_LEVEL: pino levels, default info. Use debug on the first run so you can see where it stalls.
• PORT: default 3123.
• WHISPER_VERBOSE: forwards whisper.cpp output, default false.

Tuning, if the defaults fight your hardware:

• KOKORO_MODEL_PRECISION: fp32, fp16, q8, q4, q4f16
• CONCURRENCY: how many browser tabs Remotion renders with
• VIDEO_CACHE_SIZE_IN_BYTES: frame cache

The README marks a fourth group as a danger zone (WHISPER_MODEL, DATA_DIR_PATH, DOCKER, DEV). Leave those alone unless you are debugging the project itself.

The MCP part: letting an agent drive it

This is the piece that makes it interesting in 2026, and the piece most write-ups skip.

The server exposes MCP at /mcp/sse and /mcp/messages, with two tools:

• create-short-video, which the README describes as the LLM figuring out the right configuration itself
• get-video-status

Point Claude Code, Cursor, or any MCP client at the running server (default http://localhost:3123) and video creation becomes something you ask for in a sentence rather than a JSON body you hand-write. The agent picks voice, music mood, caption position, and orientation itself.

If you prefer HTTP, the REST surface is small and complete:

Method	Endpoint
GET	/health
POST	/api/short-video
GET	/api/short-video/{id}/status
GET	/api/short-video/{id}
GET	/api/short-videos
DELETE	/api/short-video/{id}
GET	/api/voices
GET	/api/music-tags

Per-video options: paddingBack, music, captionPosition, captionBackgroundColor, voice, orientation, musicVolume.

What it cannot do, in the project's own words

The README is unusually honest here, and these limits decide whether this tool is for you:

• English voiceover only.
• Background videos come from Pexels. No other source.
• It cannot accept images or videos as input.
• It cannot generate video from your images.
• You cannot supply your own footage.

Read those four together and a boundary appears: this is a machine for narration over stock footage. It is genuinely good at that, and that format has a real audience: quote-over-b-roll, listicles, explainer shorts, faceless niche channels.

But if you sell a physical product, the thing you sell can never be on screen. That is not a limitation you work around. It is a category boundary. Same if your market is not English-speaking, or if your winning format is a person talking to camera.

Who should run it

Run it if you want faceless narration-over-stock shorts, you are comfortable with Docker or a terminal, you want zero per-video cost, and you like the idea of an agent making videos on request through MCP.

Look elsewhere if your product needs to appear on screen, you need a language other than English, or your format depends on a person: a face, a demo, a pair of hands opening a box.

If you land in the second group, the question changes from "which generator" to "how do I get my own product into a format that already works." That is the lane Riffkit sits in: you give it one TikTok that is already winning, it extracts the emotion formula, and rebuilds that formula around your product and your character, in nine languages, billed by the second of video you keep. Hosted, no install, and it also ships as an agent skill if you would rather stay in Claude Code.

Different tools, different jobs. Short Video Maker is free and self-hosted and does not want your footage; that is a coherent design, not a flaw. Go star the repo if it fits your format.

Sources

• short-video-maker README — install commands, image tags, environment variables, endpoints, stated limitations
• Docker Hub: gyoridavid/short-video-maker — image tags
• PulseMCP listing — MCP server surface