# remotion-mcp-server

An MCP (Model Context Protocol) server that gives Claude the ability to **analyze reference videos and generate branded Instagram Reels / YouTube Shorts** using [Remotion](https://www.remotion.dev/) (React-based programmatic video) — entirely from a chat conversation.

Point Claude at a reference reel, and it can:
1. Download it (`yt-dlp`), pull out frames + audio, and get a **full transcript** (YouTube captions first, [faster-whisper](https://github.com/SYSTRAN/faster-whisper) fallback for everything else — Instagram, TikTok, local files).
2. Generate a new composition in the same style — dialogue-bubble reels or fact/listicle reels — as real React/TSX code.
3. Render it to MP4 with Remotion.
4. Tell you how to open it in **Remotion Studio** to scrub and review before you call it final.

No CapCut, no manual editing — Claude writes the video.

## Tools

| Tool | What it does |
|---|---|
| `analyze_video(url)` | Downloads a reference video from YouTube/Instagram/Facebook/direct URL. Extracts frames at 0.5fps, audio, duration, and a full transcript (captions or Whisper). |
| `create_dialogue_reel(...)` | Generates an animated speaker-bubble dialogue reel (Remotion TSX) and renders it to MP4. |
| `create_facts_reel(...)` | Generates a facts/listicle-style reel with animated bullet points and renders it to MP4. |
| `render_composition(id)` | Re-renders any existing composition in the project. |
| `list_outputs()` | Lists rendered MP4s in the output folder. |

Both `create_*` tools return a `preview` hint telling Claude/you how to open the composition in Remotion Studio (`npm run dev` → `localhost:3000`) before treating the render as final.

## Setup

**1. Clone and install Python deps**

```bash
git clone https://github.com/<your-username>/remotion-mcp-server.git
cd remotion-mcp-server
pip install -r requirements.txt
```

You'll also need `ffmpeg` on your PATH (or install `imageio-ffmpeg`, which the server falls back to automatically).

**2. Set up the Remotion project**

This server needs a Remotion project to write generated compositions into and render from. A ready-to-use starter is included:

```bash
cd remotion-template
npm install
cd ..
```

Or point `REMOTION_MCP_PROJECT` at your own existing Remotion project — it just needs the two marker comments from `remotion-template/src/Root.tsx` present in its `Root.tsx`.

**3. Configure (optional)**

Copy `.env.example` to `.env` and adjust if you're not using the defaults (custom yt-dlp/ffmpeg paths, a different project folder, a default watermark).

**4. Register with Claude**

Add to your Claude Desktop / Claude Code MCP config:

```json
{
  "mcpServers": {
    "remotion-video": {
      "command": "python",
      "args": ["/absolute/path/to/remotion-mcp-server/server.py"]
    }
  }
}
```

Restart Claude, and ask it to analyze a reference reel and build you one in the same style.

## How it works

- `analyze_video` downloads with `yt-dlp`, extracts frames + audio with `ffmpeg`, then transcribes: YouTube captions via `youtube-transcript-api` first, falling back to local `faster-whisper` transcription for everything else.
- `create_dialogue_reel` / `create_facts_reel` template out a `.tsx` composition file, register it in the Remotion project's `Root.tsx` between marker comments, and call `npx remotion render`.
- Generated compositions show up live in Remotion Studio (`npm run dev`) via hot-reload — no restart needed — so you can scrub through and review before treating a render as final.

## License

MIT — see [LICENSE](LICENSE).