video-studio-mcp

An MCP server that builds narrated 9:16 documentary videos (TikTok / Reels / Shorts) end to end, entirely on your own machine:

Wikimedia Commons images → AI voiceover → Remotion render → MP4 + QA frames + publishing copy.

You describe a topic; the assistant picks images, writes the storyboard, narrates it, renders it, and hands you the file plus a title/description/hashtags.

The bundled template and default voices are Vietnamese-first. The pipeline itself is language-agnostic — pass any ElevenLabs voice and write the narration in whatever language you want.

Requirements

Without an ElevenLabs key the server falls back to the macOS say command — noticeably lower quality, and macOS only. On Linux/Windows a key is required.

The server checks for ffmpeg before starting any job and tells you exactly what is missing, rather than failing silently inside a background render.

Related MCP server: ittybitty MCP server

Install

Add to your MCP client config:

{
  "mcpServers": {
    "video-studio": {
      "command": "npx",
      "args": ["-y", "video-studio-mcp"]
    }
  }
}

Restart the client afterwards.

Your API key

No API key ships with this package. You supply your own, one of two ways:

Option A — put it in the MCP config (standard, key never enters a chat transcript):

{
  "mcpServers": {
    "video-studio": {
      "command": "npx",
      "args": ["-y", "video-studio-mcp"],
      "env": { "ELEVENLABS_API_KEY": "sk_your_key_here" }
    }
  }
}

Option B — let the assistant ask you. Just start making a video. When a key is needed, the server says so and the assistant asks for yours, then calls its set_api_key tool. The key is written to ~/.config/video-studio/config.json with 0600 permissions and never leaves your machine.

Resolution order: ELEVENLABS_API_KEY env → ~/.config/video-studio/config.json → ~/.claude/elevenlabs.env.

Ask "where is my video-studio key coming from?" and the assistant will report the active source.

Usage

Just ask, in any language:

"Make a video about the Battle of Bach Dang, 938."

The assistant will:

1. list_templates — show the available looks and ask you to pick one. This is the one decision it will not make for you.

2. search_wikimedia_images — find freely-licensed (PD / CC) photos, recording license + author for every one.

3. create_video — scaffold the Remotion project, download images, write the storyboard, generate the voiceover, and render. Runs in the background.

4. project_status wait_for='build' — returns the MP4 path plus four QA frames, which the assistant inspects for layout, legible text, correct diacritics, and mis-cropped subjects.

5. write_publish_meta — a hook title, a description with image credits, and hashtags, saved to publish.txt / publish.json.

Output lands in ~/Work/VideoReview/<slug>/ — change that with the VIDEO_STUDIO_BASE environment variable.

<slug>/
├── out/video.mp4      the finished video
├── content.json       the storyboard — edit and re-render to tweak
├── public/images/     downloaded source images
├── public/voiceover/  per-scene narration mp3s
├── qa/                extracted QA frames
└── publish.txt        title + description + hashtags, ready to paste

Tools

Configuration

Per-video overrides live in that project's content.json under meta: voiceId, voiceSpeed, voiceModel. meta beats the environment — so each template can own its voice without a global setting silently overriding it.

Templates

Adding one: create templates/<id>/ containing template.json (manifest), Composition.tsx, and optionally poster.jpg. The server rescans the directory on every call — no server code to change.

Shared building blocks live in templates/_shared/: Ken Burns motion, photo layouts, scene dissolves, Vietnamese text normalisation. Reuse them instead of rewriting.

Using it as a Claude Code skill

skill/SKILL.md documents the full workflow including a shell-only path that bypasses MCP. To install:

mkdir -p ~/.claude/skills/video-studio
cp -R "$(npm root -g)/video-studio-mcp/"{base,templates,scripts} ~/.claude/skills/video-studio/
cp "$(npm root -g)/video-studio-mcp/skill/SKILL.md" ~/.claude/skills/video-studio/

Pick one path — MCP or CLI, never both. Both drive the same npm run scripts in the same project directory, so mixing them renders twice and can overwrite the MP4 mid-write.

Gotchas worth knowing

• Vietnamese ALL-CAPS with hook accents. Chromium renders Ỷ Ủ Ổ Ả Ẩ as acute accents. Keep titles sentence-case; write_content rejects the dangerous cases outright.

• Wikimedia rate limits. upload.wikimedia.org returns 429 aggressively for original file URLs. The downloader asks the API for a /thumb/ URL first and retries with backoff.

• Reused slugs. A directory built by another template is refused rather than rendered over — different templates render to different filenames, which used to hang status polling forever.

• Ultra-wide images (aspect > 1.9) crop badly as fullbleed; use editorial or framed.

Licensing of what you make

Everything is sourced from Wikimedia Commons (Public Domain / CC). Credit your sources — CC-BY and CC-BY-SA require attribution when you publish. The closing scene and the generated description both carry credits; keep them.

License

MIT