video-studio-mcp
Provides text-to-speech voiceover generation using ElevenLabs API.
Searches and downloads freely-licensed images from Wikimedia Commons.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@video-studio-mcp Make a video about the history of coffee."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 | |
ffmpeg + ffprobe | measuring narration length, extracting QA frames |
|
ElevenLabs API key | real voiceover | free key at elevenlabs.io |
ImageMagick (optional) | slightly nicer thumbnails; ffmpeg is used otherwise |
|
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: SceneWeaver MCP
Install
Add to your MCP client config:
{
"mcpServers": {
"video-studio": {
"command": "npx",
"args": ["-y", "video-studio-mcp"]
}
}
}Client | Config file |
Claude Desktop |
|
Claude Code |
|
Cursor / Cline / others | their own |
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 pasteTools
Tool | What it does |
| every template with its look and what it suits |
| the |
| find PD/CC images (title, license, author, dimensions, URL) |
| download URLs and return thumbnails to eyeball |
| one-shot: scaffold + images + storyboard + voiceover + render |
| the same pipeline, step by step |
| poll a background job; returns duration, audio check, QA frames |
| save title + description + hashtags |
| save your ElevenLabs key, or report where the current one comes from |
Configuration
Variable | Default | Purpose |
| — | your key; highest priority |
|
| where projects are created |
| 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 |
| 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_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
Available Tools
13 toolsadd_imagesAdd images to projectA
Download chosen Wikimedia images into /public/images/. Pass the direct URLs from search results and a short filename for each (e.g. 'ngomon.jpg'). In content.json reference them as 'images/'.
Inputs: slug (required), images (required).
create_videoCreate the whole video (one-shot, autonomous)A
ONE-SHOT builder — the preferred path. Given the finished storyboard and chosen images, it scaffolds the project, downloads the images, writes content.json, then runs voiceover + render in ONE background job. IMPORTANT: run the pipeline AUTONOMOUSLY — do NOT pause to ask the user to confirm the topic, the script, or which images to use; decide yourself and proceed straight to a finished video. Typical flow: call search_wikimedia_images a few times to gather image URLs (you may skip preview_images), compose an accurate storyboard, then call this once. Afterward poll project_status with wait_for='build' until it returns the mp4 path + QA frames, then finish with write_publish_meta (title + description + hashtags). content_json = the full content.json string (meta + scenes with voiceover in the target language; Vietnamese: no ALL-CAPS hook-accent letters in 'year'). images = [{url, filename}] matching the 'images/' paths used in content_json.
Inputs: slug (required), images (required), template (required), content_json (required), +1 more.
generate_voiceoverGenerate voiceover (background job)A
Start generating the Vietnamese/target-language voiceover for every scene using ElevenLabs eleven_turbo_v2_5 with the default Northern-accent Vietnamese voice 'Hien' (falls back to macOS say if no key at ~/.claude/elevenlabs.env). Runs in the BACKGROUND and returns immediately. Then call project_status with wait_for='voiceover' to wait for completion. Optionally pass an ElevenLabs voice_id.
Inputs: slug (required), voice_id.
list_templatesList video templatesARead-only
START HERE for any 'make a video about X' request. Returns every available template with id, name, what it looks like, and what it is best for — plus a poster image when one exists. AFTER calling this you MUST let the user pick: present the templates and ask them to choose (use your AskUserQuestion tool so the choice renders the same in the desktop app and the terminal). Do NOT pick a template silently on the user's behalf. Once they choose, call template_schema with that id.
Inputs: no named parameters.
new_video_projectScaffold a video projectA
Create a new Remotion project at ~/Work/VideoReview// using the chosen template. Runs npm install (~15s). Do this once per video, after the user picked a template, before adding images or writing content.
Inputs: slug (required), template (required).
preview_imagesPreview candidate imagesARead-only
Download the given image URLs and return small thumbnails so you can visually judge which to use before committing. Use after search_wikimedia_images when you need to see the images.
Inputs: urls (required).
project_statusCheck project / wait for a jobARead-only
Report voiceover + render progress for a project. With wait_for='voiceover' it waits (up to ~50s) until all scene mp3s exist; with wait_for='render' it waits until out/video.mp4 is ready, then returns the duration, whether audio is present, and 4 QA frames as images (inspect them: layout, readable text, correct diacritics; if a subject is mis-cropped, adjust focalX/focalY in content.json and re-render). If a job is still running after the wait, call again.
Inputs: slug (required), wait_for.
render_videoRender the video (background job)A
Start the Remotion render (-> out/video.mp4). Runs in the BACKGROUND and returns immediately. Do this AFTER voiceover finished (so scene lengths match narration). Then call project_status with wait_for='render' to get the final duration and QA frames.
Inputs: slug (required).
search_wikimedia_imagesSearch Wikimedia imagesARead-only
Find freely-licensed (Public Domain / CC) images on Wikimedia Commons for a topic. Search with ENGLISH keywords for best results (e.g. 'Tomb of Minh Mang Hue', 'Angkor Wat aerial'). Returns candidates with title, license, author, pixel dimensions and a downloadable URL. Pick images >= ~1000px; prefer old public-domain photos for a documentary feel. ALWAYS keep the license+author of every image you use to credit sources in the closing scene. AUTONOMY: do NOT stop to ask the user which results to use — pick the best yourself. (The ONE thing you must ask about is the template, via list_templates.)
Inputs: query (required), limit.
set_api_keySave the user's ElevenLabs API keyAIdempotent
Save the USER'S OWN ElevenLabs API key so this machine can generate real voiceovers. Call this only when a tool reports that no key is configured, or when the user offers a key. Ask the user for their key first — get one free at https://elevenlabs.io/app/settings/api-keys — and NEVER invent one. The key is written to ~/.config/video-studio/config.json with 0600 permissions and never leaves this machine. Alternative for users who prefer not to type a key into chat: put ELEVENLABS_API_KEY in the 'env' block of their MCP client config instead; that always wins over the saved file. Call with no arguments to just report where the current key comes from.
Inputs: api_key.
template_schemaGet one template's content.json schemaARead-only
Return the content.json schema, scene outline and hard rules for ONE template. Call this after the user picked a template, before writing any content. Each template has its OWN scene types — do not reuse another template's shape.
Inputs: template (required).
write_contentWrite content.json (storyboard)AIdempotent
Write the video storyboard to /content.json. Pass the COMPLETE JSON as a string. Schema: meta{fps:30,width:1080,height:1920,accent,accentSoft,voice:false} and scenes[] where each scene has id, type ('title'|'photo'|'timeline'|'closing'), dur, voiceover (1-2 sentences in the target language), image ('images/..'), focalX/focalY. title{kicker,title,subtitle}; photo{year,headline,caption}; timeline{title,items:[{year,text}]}; closing{title,note,cta}. Vietnamese: DO NOT write ALL-CAPS text with hook-accent letters (Ỷ/Ủ/Ổ/Ả/Ẩ) in 'year' badges; use numbers or hook-free words. Facts must be accurate; credit image sources in closing 'note'.
Inputs: slug (required), content_json (required).
write_publish_metaWrite title, description & hashtagsAIdempotent
FINAL STEP, right after the render is done: save the publishing copy for the video — a hook title, a description, and hashtags. Write them in the SAME language as the voiceover, from the video's real content (do not promise anything the video does not show). title: <= 100 chars, one strong hook. description: 2-4 sentences — what the viewer gets, plus image credits (author + license) when the images are CC-BY/CC-BY-SA. hashtags: 5-12, each ONE word (no spaces), mixing broad tags with topic-specific ones. Saves /publish.json + a copy-paste ready /publish.txt, and returns the text so you can show it to the user.
Inputs: slug (required), title (required), hashtags (required), description (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 13 tools
Most tools are clearly distinct. The minor overlap is between create_video (one-shot builder) and the individual step tools (new_video_project, add_images, write_content, etc.) but descriptions make the two workflows clear.
All tool names follow a consistent verb_noun pattern (e.g., list_templates, search_wikimedia_images, write_content) with no mixing of conventions.
13 tools is appropriate for a video creation server, covering setup, template selection, asset sourcing, project creation, generation, and publishing without excess.
Covers the full video creation pipeline from key setup to final publish metadata. Minor gaps: no tool to list existing projects or edit content incrementally, but the core workflow is complete.
Maintenance
Related MCP Connectors
Generate free documentary storyboards and render 5–15 min narrated 1080p MP4 documentaries.
Turn a topic, URL, or document into a narrated, animated explainer video.
Turn documents and photos into narrated AI videos from Claude, ChatGPT, Codex or any MCP client.
Make faceless YouTube videos and Shorts from a topic or script, then publish to YouTube.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to generate narrated videos from topics or scripts, with stock footage, home videos, or local AI clips.2MIT
- AlicenseBqualityCmaintenanceEnables an assistant to create storyboard-driven narrated short videos locally, including scene planning, media search/import, voice previews, captions, branding, and duration-controlled MP4 export without an LLM API key.12Apache 2.0
- AlicenseBqualityCmaintenanceTurns a topic into a short vertical animated video with sound by having the AI client pick one of 29 built-in visual looks, edit a working page, and render it to MP4 locally. Everything runs on the user's own machine with no API keys and nothing uploaded, and narration can be added from files, a command, or an HTTP speech endpoint.13MIT
- AlicenseAqualityBmaintenanceAn MCP server that turns a topic into a finished narrated, subtitled short video — neural voice-over, stock footage retrieval, word-highlighted styled captions, background music and 9:16/16:9/1:1 ffmpeg rendering — plus voiceover generation, voice browsing, footage preview and environment checks. It runs the whole pipeline inside Claude with no LLM API key required.5MIT