remotion-motion-mcp

An MCP server for creating, editing, validating, previewing, and rendering local Remotion video projects.

Features

Project Management

• ping — Health check with environment and workspace info
• create_remotion_project — Creates a local Remotion project with default animation
• list_remotion_projects — Lists valid projects from REMOTION_MCP_WORKSPACE
• get_project_structure — Returns directory tree with configurable maxDepth
• validate_remotion_project — Checks project integrity and readiness for rendering

File Operations

• read_project_file — Safely reads text files; binary files return metadata only
• write_project_file — Safely writes files inside an existing project with path traversal protection

Preview and Render

• preview_remotion_project — Launches Remotion Studio for a project
• render_remotion_project — Renders MP4 output with strict preflight validation

Note: preview_remotion_project can launch Remotion Studio, but long-running preview processes should be tested manually.

render_remotion_project can render MP4 files, but large renders may exceed MCP client request timeouts. Automated tests use preflight checks and a tiny render smoke test.

Installation

cd remotion-motion-mcp
npm install
npm run build

To install globally (after publishing to npm):

npm install -g remotion-motion-mcp

MCP Configuration

Add to your Claude Code / Cursor / MCP client configuration:

{
  "mcpServers": {
    "remotion-motion-mcp": {
      "command": "node",
      "args": ["E:/test/remotion-motion-mcp/dist/index.js"],
      "env": {
        "REMOTION_MCP_WORKSPACE": "E:/test/remotion-workspace"
      }
    }
  }
}

REMOTION_MCP_WORKSPACE is required for workspace isolation. If not set, the server falls back to a default local workspace directory.

Usage Flow

Recommended workflow:

1. create_remotion_project — scaffold a new project
2. list_remotion_projects — verify the project was created
3. get_project_structure — explore the project layout
4. read_project_file — read source files
5. write_project_file — edit source files
6. validate_remotion_project — check project integrity
7. preview_remotion_project or manual npm run dev — preview in Remotion Studio
8. render_remotion_project or manual npx remotion render — render to MP4

Tool Summary

ping

Health check with environment and workspace info.

create_remotion_project

Creates a local Remotion project with:

• src/index.ts — entry point containing registerRoot(Root)
• src/Root.tsx — defines the Composition
• src/Main.tsx — contains the default animation
• package.json
• motion-project.json

Generated templates avoid undefined fps / width / height variables. spring() calls include fps from useVideoConfig().

list_remotion_projects

Lists valid projects from REMOTION_MCP_WORKSPACE.

get_project_structure

Returns directory tree with maxDepth. Ignores heavy / unsafe directories like node_modules, .git, out, dist, .remotion.

read_project_file

Safely reads text files. Binary files return metadata only. Forbidden directories are blocked.

write_project_file

Safely writes files inside an existing project. Blocks path traversal and dangerous directories/files. Does not create arbitrary projects.

validate_remotion_project

Checks:

• project directory exists
• motion-project.json exists and is valid
• package.json exists and is valid
• Remotion dependency is installed
• dev/render scripts exist in package.json
• entry file exists
• registerRoot is called
• Root.tsx has a Composition
• No undefined variable mistakes
• Main.tsx spring() uses correct fps
• node_modules exists
• out directory

preview_remotion_project

Starts Remotion Studio for a project. Regular automated tests only cover preflight and fast-fail behavior.

Manual preview command:

cd E:/test/remotion-workspace/remotion-render-basic
npm run dev

render_remotion_project

Renders MP4 output with strict preflight validation (10 sequential checks). Automated tests include preflight/security checks and a tiny render smoke test. Large renders may need manual testing or a client with a longer request timeout.

Manual render command:

cd E:/test/remotion-workspace/remotion-render-basic
npx remotion render src/index.ts Main out/manual-render-test.mp4

Testing

Passed

• Full lightweight regression (full-light-regression.json): 28/28 passed
• Render preflight and security tests passed
• Preview preflight and security tests passed
• Tiny real render smoke test passed
• Manual Remotion Studio preview verified

Not included in normal regression

• Long real render tests
• Long-running preview server tests

These are intentionally excluded because they can exceed MCP client request timeouts or leave long-running processes.

Security

• Workspace isolation — all operations restricted to REMOTION_MCP_WORKSPACE
• Path traversal prevention — ../ and absolute paths outside workspace are blocked
• Forbidden directories — node_modules, .git, dist, out, .remotion, .remotion-mcp are protected
• Lockfile protection — write_project_file cannot modify package-lock.json, yarn.lock, etc.
• Binary file safety — binary files are detected and handled gracefully
• Command injection prevention — all commands use execa with command + args, no shell string concatenation
• No stdout pollution — logging goes to stderr only (MCP uses stdio transport)

Limitations

• Remotion only — no HyperFrames support yet
• No composition management tools (create/list/update/delete compositions)
• No asset management tools (upload/list/delete assets)
• No render progress streaming
• Long renders may exceed MCP client request timeout
• Preview is a long-running process and should be tested carefully

Version

Current version: 0.1.0