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

	Needed for	Install
Node.js ≥ 20	everything	nodejs.org
ffmpeg + ffprobe	measuring narration length, extracting QA frames	brew install ffmpeg · sudo apt install ffmpeg · winget install Gyan.FFmpeg
ElevenLabs API key	real voiceover	free key at elevenlabs.io
ImageMagick (optional)	slightly nicer thumbnails; ffmpeg is used otherwise	brew install imagemagick

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.

---

Install

Add to your MCP client config:

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

Client	Config file
Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json (macOS) · %APPDATA%\Claude\claude_desktop_config.json (Windows)
Claude Code	claude mcp add video-studio -- npx -y video-studio-mcp
Cursor / Cline / others	their own mcp.json — same shape

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

Tool	What it does
list_templates	every template with its look and what it suits
template_schema	the content.json schema for one template
search_wikimedia_images	find PD/CC images (title, license, author, dimensions, URL)
preview_images	download URLs and return thumbnails to eyeball
create_video	one-shot: scaffold + images + storyboard + voiceover + render
new_video_project · add_images · write_content · generate_voiceover · render_video	the same pipeline, step by step
project_status	poll a background job; returns duration, audio check, QA frames
write_publish_meta	save title + description + hashtags
set_api_key	save your ElevenLabs key, or report where the current one comes from

---

Configuration

Variable	Default	Purpose
ELEVENLABS_API_KEY	—	your key; highest priority
VIDEO_STUDIO_BASE	~/Work/VideoReview	where projects are created
ELEVENLABS_VOICE_ID	template's voice	override the narrator globally

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

id	Look	Best for
history	aged paper, serif type, sepia photos in frames, year seals, timeline	historical figures, dynasties, monuments, heritage sites, past events

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