# Remotion Video Production MCP Server

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![MCP Protocol](https://img.shields.io/badge/MCP-Model%20Context%20Protocol-blue.svg)](https://modelcontextprotocol.io/)

A world-class Model Context Protocol (MCP) server that acts as an intelligent bridge for AI agents to analyze audio beats, synthesize voices with Google Gemini TTS, and programmatically construct and render professional videos using **Remotion (v4.0+)** and **React**.

Supports **BOTH**:
- 💻 **Local STDIO Transport**: For local AI clients (Antigravity, Claude Desktop, Cursor).
- 🌐 **Remote Streamable HTTP Transport**: For cloud deployments (Render) and web-based AI clients (Claude Web at [https://claude.ai/new](https://claude.ai/new)).

---

## 🚀 Key Features

* 🎬 **Programmatic Scaffolding**: Create zero-config React/Remotion video projects with built-in aspect ratios: TikTok/Reels (`tiktok-916`), YouTube (`youtube-169`), and Social (`social-11`).
* 🎙️ **Gemini 3.1 Flash TTS integration**: Generate high-fidelity voiced scene dialogues with regional accents, and produce word-level timecodes for kinetic subtitles.
* 🎵 **Librosa Audio Beat Sync**: Analyze background music to extract BPM, beat boundaries, RMS energy drops/rises, and recommend frame-accurate scene cuts.
* 📸 **Visual Preview Snapshots**: Instantly render frame snapshots (PNG/JPEG/WebP) at any frame index for AI visual verification.
* ⚡ **Headless Rendering**: Programmatically compile high-quality MP4/WebM videos with multi-core concurrency control and progress tracking.
* 🔒 **Bearer Token Authentication**: Secure your HTTP MCP endpoints when deployed to public cloud services.

---

## 🛠️ Prerequisites

To run this MCP server and render videos, the host environment requires:

1. **Node.js** (v20.0.0 or higher recommended) and **npm**.
2. **Python 3** (v3.10+ recommended) with audio packages installed:
   ```bash
   pip install librosa numpy scipy google-genai
   ```
3. **Remotion Browser Dependencies**: Launching Chrome headless requires Chromium. Install via CLI:
   ```bash
   npx @remotion/cli browser ensure
   ```

---

## 🌐 Remote MCP / Claude Web & Streamable HTTP Deployment

This server supports the **MCP Streamable HTTP Transport Specification** (`@modelcontextprotocol/sdk` v1.29.0), allowing web-based clients such as **Claude Web** ([https://claude.ai/new](https://claude.ai/new)) to connect remotely.

### 1. Running the HTTP Server Locally

Build and start the Streamable HTTP server:

```bash
npm install
npm run build
npm run start:http
```

By default, the server listens on:
- **Health Check**: `GET http://localhost:3000/health`
- **MCP Endpoint**: `http://localhost:3000/mcp`

### 2. Environment Variables

Create a `.env` file or export environment variables:

| Environment Variable | Description | Default |
| :--- | :--- | :--- |
| `PORT` | HTTP Port to listen on | `3000` |
| `HOST` | Host interface binding | `0.0.0.0` |
| `MCP_AUTH_TOKEN` | Secret token for Bearer authentication (`Authorization: Bearer <token>`) | *(Unauthenticated if empty)* |
| `CORS_ORIGIN` | Allowed CORS origins (comma-separated, e.g., `https://claude.ai`) | `*` / Allow all |
| `GEMINI_API_KEY` | Google Gemini API Key for TTS synthesis | *(Synthetic audio fallback)* |

### 3. Securing the HTTP MCP Endpoint

When deploying to a public server, configure `MCP_AUTH_TOKEN`:

```bash
export MCP_AUTH_TOKEN=your-secret-token-here
npm run start:http
```

Incoming requests to `/mcp` must include the header:
```http
Authorization: Bearer your-secret-token-here
```
Requests missing or specifying an invalid token will receive a `401 Unauthorized` response.

### 4. Testing HTTP & Health Endpoints

- **Verify Health Status**:
  ```bash
  curl http://localhost:3000/health
  # Response: {"status":"ok","service":"remotion-mcp-server"}
  ```

- **Verify MCP Initialization**:
  ```bash
  curl -X POST http://localhost:3000/mcp \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer your-secret-token-here" \
    -d '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "initialize",
      "params": {
        "protocolVersion": "2024-11-05",
        "capabilities": {},
        "clientInfo": { "name": "curl-test", "version": "1.0.0" }
      }
    }'
  ```

### 5. Deployment to Render (One-Click / Blueprint)

The repository includes a `render.yaml` blueprint and a production-ready `Dockerfile` that packages Node 20, Chromium, FFmpeg, and Python audio libraries.

1. Push your repository to GitHub.
2. Sign in to [Render](https://render.com) and click **New +** -> **Blueprint**.
3. Connect your repository (`remotionMcpServer`). Render will automatically detect `render.yaml`.
4. Configure environment variables in the Render Dashboard:
   - `MCP_AUTH_TOKEN`: Your custom secret token.
   - `GEMINI_API_KEY`: Your Gemini API key.
5. Deploy! Your remote MCP URL will be:
   ```text
   https://YOUR-SERVICE-NAME.onrender.com/mcp
   ```

### 6. Connecting to Claude Web

1. Go to [https://claude.ai/new](https://claude.ai/new).
2. Open Custom MCP Connectors settings.
3. Enter your remote MCP URL:
   ```text
   https://YOUR-SERVICE-NAME.onrender.com/mcp
   ```
4. If authentication is enabled, configure the `Authorization` header with `Bearer <your-mcp-auth-token>`.
5. Save and connect. Claude Web will list all 5 available Remotion tools.

---

## 💻 Local STDIO Setup (Antigravity & Local Clients)

### Instant One-Command Setup (Recommended)

Copy and paste a single command into your terminal:

#### 🍎 macOS / Linux (Terminal)
```bash
curl -fsSL https://raw.githubusercontent.com/ivalenzuela/remotion-mcp-server/main/autoinstall.sh | bash
```

#### 🪟 Windows (PowerShell)
```powershell
iwr -useb https://raw.githubusercontent.com/ivalenzuela/remotion-mcp-server/main/autoinstall.ps1 | iex
```

### Manual STDIO Configuration

1. **Compile the Server**:
   ```bash
   git clone https://github.com/ivalenzuela/remotion-mcp-server.git
   cd remotion-mcp-server
   npm install
   npm run build
   ```

2. **Register in AI Client (`mcp_config.json` / `claude_desktop_config.json`)**:
   ```json
   {
     "mcpServers": {
       "remotion": {
         "command": "node",
         "args": ["/path/to/remotion-mcp-server/dist/index.js"],
         "env": {
           "GEMINI_API_KEY": "YOUR_GEMINI_API_KEY_HERE"
         }
       }
     }
   }
   ```

---

## 🤖 Available MCP Tools

All five tools are available identically across **STDIO** and **Streamable HTTP** transports:

### 1. `remotion_scaffold_project`
Scaffolds a complete React/Remotion project with prebuilt templates, standard layout components, and automatically installs npm dependencies.
* **Arguments**:
  * `projectName` (string, required): Folder name of the target project.
  * `template` (enum: `tiktok-916`, `youtube-169`, `social-11`, required): Aspect ratio.
  * `targetDir` (string, required): Parent directory path.

### 2. `remotion_analyze_audio`
Performs signal processing on audio files using Python Librosa to return BPM, beat frames, energy profiles, recommended scene cut frame numbers, and aligns SRT subtitles.
* **Arguments**:
  * `audioPath` (string, required): Path to input audio track.
  * `srtPath` (string, optional): Path to SRT subtitles file.
  * `outputPath` (string, optional): Path to save the output JSON analysis.
  * `fps` (number, default `30`): Target composition frame rate.
  * `minSceneDuration` (number, default `3.5`): Minimum seconds between scene cuts.

### 3. `remotion_generate_tts`
Synthesizes speech using Google Gemini 3.1 Flash TTS (`gemini-3.1-flash-tts-preview`) and outputs character-weighted word timecodes. Automatically falls back to clean synthetic audio if `GEMINI_API_KEY` is not present.
* **Arguments**:
  * `text` (string, required): Dialogue text to synthesize.
  * `outputPath` (string, required): Path to save generated `.wav` file.
  * `voice` (string, default `"Puck"`): Gemini prebuilt voice name.
  * `accent` (string, optional): Optional regional accent instruction.
  * `fps` (number, default `30`): Frame rate.

### 4. `remotion_preview_frame`
Renders a still snapshot image (PNG/JPEG/WebP) of a specific frame in the composition using Remotion's CLI.
* **Arguments**:
  * `projectDir` (string, required): Path to Remotion project.
  * `compositionId` (string, required): Target Composition ID.
  * `frame` (number, default `0`): Frame index to capture.
  * `imageFormat` (enum: `png`, `jpeg`, `webp`, default `png`): Format.
  * `props` (object, optional): Input React props.

### 5. `remotion_render_video`
Compiles a composition into a production-grade video (MP4/WebM).
* **Arguments**:
  * `projectDir` (string, required): Path to Remotion project.
  * `compositionId` (string, required): Target Composition ID.
  * `outputPath` (string, optional): Output video path.
  * `concurrency` (number/string, default `"auto"`): CPU threads to utilize.
  * `codec` (string, default `"h264"`): Target codec.
  * `props` (object, optional): Input React props.

---

## 🎨 Prebuilt React Components

Scaffolded projects include these production-ready layout components:
1. **`SubtitleOverlay`**: Word-by-word active scaling and custom text shadow glows ("Efecto Lupa PRO") for dual-language subtitles.
2. **`KenBurnsImage`**: Clean interpolation-based image scaling and translation without CSS animations.
3. **`AudioSpectrum`**: Sound frequency spectrum visualizer bars reactively synchronized with the soundtrack.
4. **`LowerThird`**: Elegant lower-third pop-ups for social media profiles or name cards.

---

## 🧪 Testing & Verification

Run the full E2E test suite to verify tool execution, path resolution, and CLI rendering:
```bash
npm test
```

---

## 📄 License

This project is licensed under the [MIT License](LICENSE).