Remotion Video Production MCP Server

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.

🚀 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.

🛠️ Prerequisites

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

1. Node.js (v18.0.0 or higher) and npm.

2. Python 3 (v3.10+ recommended) with the following packages installed:

   pip install librosa numpy scipy google-genai

3. Remotion Browser Dependencies: Launching Chrome headless requires Chromium. Install it via CLI:

   npx remotion browser ensure

📦 Installation & Setup

🚀 Automated Setup (Recommended)

Run the automated installer inside the cloned repository root:

• macOS / Linux:

  chmod +x autoinstall.sh
  ./autoinstall.sh

• Windows (PowerShell):

  Set-ExecutionPolicy Bypass -Scope Process -Force
  .\autoinstall.ps1

This installer automatically compiles the codebase, installs Python packages, ensures Chrome dependencies are loaded, copies the global SKILL.md to your optimizations folder, and registers the server configuration to Claude Desktop and Antigravity.

🛠️ Manual Installation (Alternative)

1. Compile the Server:

   git clone https://github.com/ivanv/remotion-mcp-server.git
   cd remotion-mcp-server
   npm install
   npm run build

2. Register with your AI Client

Add the server configuration to your MCP settings file (e.g. claude_desktop_config.json, antigravity.json, or .mcp.json):

{
  "mcpServers": {
    "remotion": {
      "command": "node",
      "args": ["C:/Users/ivanv/PycharmProjects/remotion-mcp-server/dist/index.js"],
      "env": {
        "GEMINI_API_KEY": "YOUR_GEMINI_API_KEY_HERE"
      }
    }
  }
}

🤖 Available MCP Tools

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:

npm test

📄 License

This project is licensed under the MIT License.