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