# 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](https://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](https://elevenlabs.io/app/settings/api-keys) |
| 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:

```json
{
  "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):

```json
{
  "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:

```bash
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