Content
# Remotion Media MCP
An MCP (Model Context Protocol) server for AI-powered media generation in Remotion projects. Generate images, videos, music, and sound effects directly from Claude or any MCP-compatible client.
## Features
- **Image Generation** - AI images via Nano Banana Pro
- **Video Generation** - Text-to-video and image-to-video via Veo 3.1
- **Music Generation** - AI music via Suno (V3.5 - V5)
- **Sound Effects** - AI sound effects via ElevenLabs SFX V2
- **Text-to-Speech** - Natural voiceovers via ElevenLabs TTS
- **Subtitle Generation** - Transcribe audio/video to SRT via local Whisper
- **Asset Library** - Browse, back up, and pull assets with AID tracking via optional Airtable integration
## Installation
```bash
npm install -g remotion-media-mcp
```
Or use with npx:
```bash
npx remotion-media-mcp
```
## Configuration
### Get an API Key
1. Sign up at [kie.ai](https://kie.ai)
2. Get your API key from the dashboard
### Claude Desktop
Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
```json
{
"mcpServers": {
"remotion-media": {
"command": "npx",
"args": ["remotion-media-mcp"],
"env": {
"KIE_API_KEY": "your-api-key-here",
"AIRTABLE_API_KEY": "your-airtable-pat-here",
"AIRTABLE_BASE_ID": "appXXXXXXXXXXXXXX",
"AIRTABLE_TABLE_NAME": "Assets"
}
}
}
}
```
### Claude Code (CLI)
Add with a single command:
```bash
claude mcp add remotion-media -s project -e KIE_API_KEY=your-api-key -e AIRTABLE_API_KEY=your-airtable-pat -e AIRTABLE_BASE_ID=appXXX -e AIRTABLE_TABLE_NAME=Assets -- npx remotion-media-mcp
```
Or manually add to your project's `.mcp.json`:
```json
{
"mcpServers": {
"remotion-media": {
"command": "npx",
"args": ["remotion-media-mcp"],
"env": {
"KIE_API_KEY": "your-api-key-here",
"AIRTABLE_API_KEY": "your-airtable-pat-here",
"AIRTABLE_BASE_ID": "appXXXXXXXXXXXXXX",
"AIRTABLE_TABLE_NAME": "Assets"
}
}
}
}
```
> **Note:** The Airtable env vars are optional. Without them, everything works exactly as before. See [Airtable Integration](#airtable-integration-optional) for setup details.
## Available Tools
### `generate_image`
Generate AI images using Nano Banana Pro.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | Yes | Text description of the image |
| `output_name` | string | Yes | Output filename (without extension) |
| `aspect_ratio` | enum | No | 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9, auto |
| `resolution` | enum | No | 1K, 2K, 4K (default: 1K) |
| `image_urls` | string[] | No | Reference images (up to 8) |
### `generate_video_from_text`
Generate videos from text prompts using Veo 3.1.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | Yes | Text description of the video |
| `output_name` | string | Yes | Output filename (without extension) |
| `model` | enum | No | veo3 (quality) or veo3_fast (default) |
| `aspect_ratio` | enum | No | 16:9 (default), 9:16, Auto |
### `generate_video_from_image`
Animate images or create transitions between frames using Veo 3.1.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | Yes | Description of the animation |
| `image_urls` | string[] | Yes | 1-2 image URLs |
| `output_name` | string | Yes | Output filename (without extension) |
| `model` | enum | No | veo3 (quality) or veo3_fast (default) |
| `aspect_ratio` | enum | No | 16:9 (default), 9:16, Auto |
### `generate_music`
Generate AI music using Suno.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | Yes | Description of the music (max 500 chars) |
| `output_name` | string | Yes | Output filename (without extension) |
| `instrumental` | boolean | No | Instrumental only, no vocals (default: false) |
| `model` | enum | No | V3_5, V4, V4_5, V4_5PLUS, V5 (default) |
### `generate_sound_effect`
Generate AI sound effects using ElevenLabs SFX V2.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | Yes | Description of the sound (max 450 chars) |
| `output_name` | string | Yes | Output filename (without extension) |
| `duration_seconds` | number | No | Duration 0.5-22 seconds |
| `loop` | boolean | No | Generate seamless loop (default: false) |
### `generate_speech`
Convert text to natural-sounding speech using ElevenLabs TTS.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `text` | string | Yes | Text to convert to speech (max 5000 chars) |
| `output_name` | string | Yes | Output filename (without extension) |
| `voice` | enum | No | Voice name (default: Eric). Options: Rachel, Aria, Roger, Sarah, Laura, Charlie, George, Callum, River, Liam, Charlotte, Alice, Matilda, Will, Jessica, Eric, Chris, Brian, Daniel, Lily, Bill |
| `model` | enum | No | multilingual_v2 (quality) or turbo_v2_5 (default, faster) |
| `stability` | number | No | Voice stability 0-1 (default: 0.5) |
| `similarity_boost` | number | No | Voice similarity 0-1 (default: 0.75) |
| `speed` | number | No | Speech speed 0.7-1.2 (default: 1.0) |
### `generate_subtitles`
Transcribe audio/video files to SRT subtitles using local Whisper. Requires [whisper.cpp](https://github.com/ggerganov/whisper.cpp) or [OpenAI Whisper](https://github.com/openai/whisper) to be installed.
```bash
# Install whisper.cpp (recommended)
brew install whisper-cpp
# Or install OpenAI Whisper
pip install openai-whisper
```
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `input_file` | string | Yes | Filename in public/ folder (e.g., 'video.mp4') |
| `output_name` | string | No | Output filename without extension (default: input filename) |
| `language` | string | No | Language code e.g., 'en', 'es', 'fr' (default: auto-detect) |
| `model` | enum | No | tiny, base (default), small, medium, large |
**Note:** Models are automatically downloaded on first use (~75MB for base model).
### `list_assets`
Browse assets stored in the asset library. Requires Airtable integration to be configured.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `file_type` | enum | No | Filter by type: image, video, audio, subtitle, other |
| `max_records` | number | No | Max records to return (default: 20, max: 100) |
| `page_offset` | string | No | Pagination offset from previous call |
### `backup_asset`
Back up a local file to the asset library. Creates a record with metadata, uploads the file attachment, and assigns an AID. Files in `assets/` are automatically renamed with the AID prefix.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `file_path` | string | Yes | Path to local file (e.g., 'assets/hero.png', 'out/video.mp4') |
| `description` | string | Yes | Description of the asset |
| `file_type` | enum | No | File type (auto-detected if not specified) |
| `remote_url` | string | No | Remote URL to use as attachment instead of uploading |
### `get_asset`
Pull an asset from the library by its AID.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `aid` | string | Yes | Asset ID (e.g., 'A42') |
| `target_dir` | string | No | Target directory: 'assets' (default), 'out', 'public', or any path |
## Output Location
All generated files are saved to the `public/` directory in your current working directory, making them immediately available via Remotion's `staticFile()` function:
```tsx
import { Audio, Img, Video, staticFile } from "remotion";
// Use generated assets
<Img src={staticFile("my-image.png")} />
<Video src={staticFile("my-video.mp4")} />
<Audio src={staticFile("my-music.mp3")} />
```
## Airtable Integration (Optional)
Connect an Airtable base to automatically track every generated asset with a unique AID (e.g., A1, A42), store metadata, and sync files between local directories and Airtable.
### Setup
1. Create an [Airtable Personal Access Token](https://airtable.com/create/tokens) with `data.records:read`, `data.records:write`, and `content:manage` scopes
2. Create an Airtable base with a table (default name: "Assets") with these fields:
| Field | Type | Notes |
|-------|------|-------|
| `AID` | Formula | `"A" & {ID}` — primary display field |
| `ID` | Auto number | Auto-incrementing integer |
| `Filename` | Single line text | |
| `Description` | Long text | |
| `File` | Attachment | |
| `MIME Type` | Single line text | |
| `Record ID` | Formula | `RECORD_ID()` |
3. Set the environment variables:
| Variable | Required | Description |
|----------|----------|-------------|
| `AIRTABLE_API_KEY` | Yes | Airtable Personal Access Token |
| `AIRTABLE_BASE_ID` | Yes | Base ID (starts with `app...`) |
| `AIRTABLE_TABLE_NAME` | No | Table name (default: `"Assets"`) |
### How It Works
- **Auto-tracking**: Every file generated by `generate_image`, `generate_video_from_text`, `generate_video_from_image`, `generate_sound_effect`, `generate_music`, and `generate_speech` is automatically registered in Airtable with its metadata and remote URL attachment
- **AID assignment**: Each asset gets a unique AID (e.g., A1, A42) read back from the Airtable formula field
- **Asset copy**: Generated files are copied to `assets/` with AID-prefixed filenames (e.g., `assets/A42-hero.png`) for traceability
- **Non-blocking**: Airtable errors never break media generation — the file is always saved to `public/` regardless
- **Push/pull**: Use `backup_asset` to push local files and `get_asset` to pull files by AID
### Limitations
Airtable attachments are limited to 5MB on free plans and 100MB on paid plans. For larger files (long videos, lossless audio), a future version may support S3 or similar object storage as an intermediary, with Airtable storing only the metadata and a reference URL.
### Without Airtable
If `AIRTABLE_API_KEY` is not set, the MCP works exactly as before. Generation tools save to `public/` only, and the asset library tools (`list_assets`, `backup_asset`, `get_asset`) return a "not configured" message.
## Development
```bash
# Clone the repo
git clone https://github.com/stephengpope/remotion-media-mcp.git
cd remotion-media-mcp
# Install dependencies
npm install
# Build
npm run build
# Run locally
KIE_API_KEY=your-key node dist/index.js
```
## License
MIT
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
markitdown
Python tool for converting files and office documents to Markdown.
Fetch
Retrieve and process content from web pages by converting HTML into markdown format.
chatbox
User-friendly Desktop Client App for AI Models/LLMs (GPT, Claude, Gemini, Ollama...)
oh-my-opencode
Background agents · Curated agents like oracle, librarians, frontend...
continue
Continue is an open-source project for seamless server management.
semantic-kernel
Build and deploy intelligent AI agents with Semantic Kernel's orchestration...