<p align="center">
  <a href="https://github.com/mcp-use/remotion-mcp-app/releases/download/v1.0.0/ClaudeRemotionDemo.mp4">
    <img src="assets/demo-claude.gif" alt="Remotion MCP App Demo" width="100%"/>
  </a>
</p>

# Remotion MCP App

An [MCP App](https://mcp-use.com) for AI-powered video creation. It combines an MCP server with an interactive View — the model writes React/[Remotion](https://remotion.dev) code, the server compiles it in real-time, and a live video player renders the result directly inside the chat.

Unlike a standard MCP server that only returns text, an **MCP App** bundles a full UI View alongside its tools. The Remotion Player View renders inline in any compatible client (ChatGPT, Claude, or custom apps built with [mcp-use](https://mcp-use.com)), giving the model a visual canvas it can iterate on.

## Try it now

Connect to the hosted instance:

```
https://still-feather-l5mwy.run.mcp-use.com/mcp
```

### Setup on ChatGPT

1. Open **Settings** > **Apps and Connectors** > **Advanced Settings** and enable **Developer Mode**
2. Go to **Connectors** > **Create**, name it "Remotion", paste the URL above
3. In a new chat, click **+** > **More** and select the Remotion connector

> Requires ChatGPT Pro, Team, Enterprise, or Edu. [Full guide](https://developers.openai.com/apps-sdk/deploy/connect-chatgpt/)

### Setup on Claude

1. Open **Settings** > **Connectors** > **Add custom connector**
2. Paste the URL above and save
3. The Remotion tools will be available in new conversations

> Requires Claude Pro, Max, Team, or Enterprise. [Full guide](https://support.claude.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp)

## Demos

### ChatGPT + Remotion MCP App

[![OpenAI demo](assets/demo-openai.gif)](https://github.com/mcp-use/remotion-mcp-app/releases/download/v1.0.0/openairemotion.mp4)

### Claude + Remotion MCP App

[![Claude demo](assets/demo-claude.gif)](https://github.com/mcp-use/remotion-mcp-app/releases/download/v1.0.0/ClaudeRemotionDemo.mp4)

> Click the previews above to watch the full demos.

## How it works

This is an **MCP App** — an MCP server paired with a UI View. The two pieces work together:

1. **MCP Server** -- exposes `create_video` tool + rule tools for teaching Remotion patterns
2. **View** -- a Remotion Player that renders inline in the chat and receives compiled bundles from the server

The flow:

1. The model calls `create_video` with React/Remotion source files
2. The server compiles the project with esbuild (sub-second)
3. The compiled bundle is sent back as `structuredContent`, and the View renders it as a playable video
4. For edits, the mounted View exposes `update_video`; it sends only changed files through the server compiler and swaps the player in place

```
Model                     MCP App (Server + View)
  |                          |
  |-- create_video({files}) ->|
  |                          |-- esbuild compile
  |<- structuredContent -----|
  |                          |-- View renders video inline
  |                          |
  |-- update_video({edits}) ->|  (View tool)
  |                          |-- create_video merges + recompiles
  |                          |-- existing View swaps the player in place
```

### Single tool design

The server exposes one model-visible tool, `create_video`, for the initial composition. Once its View is mounted, the View exposes an ephemeral `update_video` tool. That tool reuses the server compiler, merges only the changed files with the current session project, and replaces the mounted player without creating another View result.

### Rule tools

The server includes teaching tools derived from the [remotion-best-practices](https://github.com/remotion-dev/skills) skill that the model can call to learn Remotion patterns:

| Tool | Topic |
|------|-------|
| `rule_react_code` | Project structure, imports, entry file contract |
| `rule_remotion_animations` | `useCurrentFrame`, frame-driven animation |
| `rule_remotion_timing` | `interpolate`, `spring`, `Easing` configs |
| `rule_remotion_sequencing` | `Sequence`, scene management, duration |
| `rule_remotion_transitions` | `TransitionSeries`, fade, slide, wipe |
| `rule_remotion_text_animations` | Typewriter effect, word highlighting |
| `rule_remotion_trimming` | Trimming with negative `Sequence` from |

### View (the "App" part)

The Remotion Player View is what makes this an MCP App rather than a plain MCP server. It runs inside the chat interface and features:

- Live video playback with controls
- Animated loading state with shader gradient while the model writes code
- Editing overlay (blur + gradient) when updating an existing video
- Ephemeral `update_video` View tool for in-place agent edits
- Fullscreen mode
- Error display with compilation error details

## Local development

### Prerequisites

- Node.js 22.22.2+
- npm or pnpm

### Setup

```bash
git clone https://github.com/mcp-use/remotion-mcp-app.git
cd remotion-mcp-app
npm install
npm run dev
```

`npm run dev` builds the View inline before opening the embedded Inspector. This keeps the v2 View compatible with the Inspector sandbox, so the animated gradient loading state mounts instead of getting stuck on the host's fallback `Compiling...` spinner. Use `npm run dev:hmr` when testing outside that embedded sandbox and Vite hot reload is more useful.

The server starts at `http://localhost:3000/mcp`.

### Connect a client

Point any MCP client at `http://localhost:3000/mcp`. For example with [mcp-use](https://mcp-use.com):

```json
{
  "mcpServers": {
    "remotion": {
      "url": "http://localhost:3000/mcp"
    }
  }
}
```

### Build and deploy

```bash
npm run build
npm run deploy
```

## Project structure

```
index.ts                     -- MCP server, tool definitions, handler
utils.ts                     -- esbuild compilation, session state, response helpers
types.ts                     -- Shared types (VideoProjectData, VideoMeta)
rules/                       -- Remotion teaching content served by rule tools
views/remotion-player/       -- MCP App View (React + Remotion Player)
  view.tsx                   -- Main View component
  types.ts                   -- Browser-only View types and runtime constants
  components/
    CodeComposition.tsx      -- CSP-safe blob module compiler + runtime shim
```

## Tool schema

```typescript
create_video({
  files: string,            // REQUIRED -- JSON string of {path: code}
  entryFile?: string,       // Default: "/src/Video.tsx"
  title?: string,
  durationInFrames?: number, // Default: 150
  fps?: number,             // Default: 30
  width?: number,           // Default: 1920
  height?: number,          // Default: 1080
})
```

The `files` parameter is a JSON string mapping virtual file paths to source code:

```json
{
  "/src/Video.tsx": "import {AbsoluteFill} from \"remotion\";\nexport default function Video() { return <AbsoluteFill />; }"
}
```

## Session behavior

- ChatGPT conversations maintain isolated project state; other clients fall back to caller or transport identity
- Calling `create_video` merges new files with the previous project
- Metadata (title, fps, dimensions) carries forward unless overridden
- Sessions are capped at 250 concurrent projects with LRU eviction

## License

MIT -- see [LICENSE](LICENSE) for details.

Note: [Remotion](https://remotion.dev) is a dependency with its own license. Free for individuals and companies with up to 3 employees. Larger organizations need a [company license](https://www.remotion.pro/license).

---

Built with [mcp-use](https://mcp-use.com) and [Remotion](https://remotion.dev). Rule tools adapted from the [remotion-best-practices](https://github.com/remotion-dev/skills) skill by Remotion.