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.
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:
list_templates— show the available looks and ask you to pick one. This is the one decision it will not make for you.search_wikimedia_images— find freely-licensed (PD / CC) photos, recording license + author for every one.create_video— scaffold the Remotion project, download images, write the storyboard, generate the voiceover, and render. Runs in the background.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.write_publish_meta— a hook title, a description with image credits, and hashtags, saved topublish.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_contentrejects the dangerous cases outright. - Wikimedia rate limits.
upload.wikimedia.orgreturns 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; useeditorialorframed.
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
