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.

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

---

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

   pip install librosa numpy scipy google-genai
   

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

   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) to connect remotely.

1. Running the HTTP Server Locally

Build and start the Streamable HTTP server:

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:

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

Incoming requests to /mcp must include the header:

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:

  curl http://localhost:3000/health
  # Response: {"status":"ok","service":"remotion-mcp-server"}
  

• Verify MCP Initialization:

  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 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:

   https://YOUR-SERVICE-NAME.onrender.com/mcp
   

6. Connecting to Claude Web

1. Go to https://claude.ai/new.
2. Open Custom MCP Connectors settings.
3. Enter your remote MCP URL:

   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)

curl -fsSL https://raw.githubusercontent.com/ivalenzuela/remotion-mcp-server/main/autoinstall.sh | bash

🪟 Windows (PowerShell)

iwr -useb https://raw.githubusercontent.com/ivalenzuela/remotion-mcp-server/main/autoinstall.ps1 | iex

Manual STDIO Configuration

1. Compile the Server:

   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):

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

npm test

---

📄 License

This project is licensed under the MIT License.