![Brandkick](brandkick-logo.png)

**Brought to you by [Brandkick](https://brandkick.pl)** - We grow brands like they're our own.

---

# After Effects MCP Server

A Model Context Protocol server for Adobe After Effects. Enables AI assistants to control After Effects through a WebSocket-based CEP panel.

## Requirements

- Adobe After Effects 2021+ (versions 18.x - 26.x)
- Node.js 18+
- pnpm

## Installation

```bash
git clone https://github.com/Brandkick/after-effects-mcp.git
cd after-effects-mcp
pnpm install
just setup
```

## Configuration

Add to Claude Code config (`~/.claude.json`):

```json
{
  "mcpServers": {
    "aftereffects": {
      "command": "node",
      "args": ["/path/to/after-effects-mcp/build/index.js"]
    }
  }
}
```

## Usage

1. Claude Code starts the MCP server automatically
2. Open After Effects
3. Open the panel: Window > Extensions > MCP Bridge

## Setup: JPEG Output Template

For `exportCompFrame` to work, create a JPEG output template in After Effects:

1. Create any composition
2. File > Export > Add to Render Queue
3. Click "Output Module" settings
4. Set Format to "JPEG Sequence"
5. Set Quality to 50-70% (faster previews, smaller files)
6. Optionally resize: check "Resize" and set to 50% or a fixed size like 960x540
7. Click the template dropdown (top of dialog)
8. Select "Save As New Template..."
9. Name it exactly: `JPEG Sequence`
10. Click OK

This only needs to be done once per After Effects installation.

## MCP Tools

| Tool                 | Description                                        |
| -------------------- | -------------------------------------------------- |
| `run-script`         | Execute any command (see Commands below)           |
| `getHelp`            | List all available commands                        |
| `createComposition`  | Create a new composition                           |
| `setLayerKeyframe`   | Set a single keyframe                              |
| `setLayerKeyframes`  | Set multiple keyframes (batch)                     |
| `setLayerExpression` | Apply expressions to properties                    |
| `setEffectKeyframes` | Animate effect properties (batch)                  |
| `importFootage`      | Import files into project                          |
| `addToRenderQueue`   | Queue composition for render                       |
| `exportCompFrame`    | Export single frame as PNG for visual verification |

## Commands

All commands can be called via `run-script`. Use `getHelp` to see full documentation.

### Project

- `getProjectInfo`, `newProject`, `saveProject`, `saveProjectAs`, `closeProject`
- `createFolder`, `moveProjectItem`, `deleteProjectItem`
- `importFootage`, `importPlaceholder`, `replaceFootage`

### Composition

- `listCompositions`, `getActiveComposition`, `createComposition`
- `setCompSettings` - Modify duration, work area, frame rate, motion blur

### Layers

- `createTextLayer`, `createShapeLayer`, `createSolidLayer`, `addLayerToComp`
- `getLayerInfo`, `setLayerProperties` - Name, transform, timing
- `setLayerFlags` - Visibility, solo, shy, locked, motion blur, 3D
- `deleteLayer`, `duplicateLayer`, `reorderLayer`, `precomposeLayer`
- `setParentLayer`, `setTrackMatte`
- `setTextProperties` - Font, size, color, justification

### Animation

- `setLayerKeyframe`, `setLayerKeyframes` (batch)
- `setLayerExpression`
- `getKeyframes`, `deleteKeyframe`, `deleteKeyframes` (batch)
- `setKeyframeEasing`, `setKeyframesEasing` (batch)
- `copyKeyframes`

### Effects

- `applyEffect`, `applyEffectTemplate`
- `listEffects`, `listAvailableEffects`, `getEffectProperties`
- `setEffectKeyframe`, `setEffectKeyframes` (batch)

### Time & Markers

- `setLayerTime` - In/out point, start time, stretch
- `enableTimeRemapping`, `setTimeRemap`
- `addMarker`, `getMarkers`, `removeMarker`

### Camera & 3D

- `createCamera`, `createLight`
- `setCameraProperties`, `setLightProperties`
- `set3DLayer`, `setMaterialOptions`

### Masks & Shapes

- `addMask`, `setMaskPath`, `setMaskProperties`, `deleteMask`
- `addShapePath`, `setShapePathVertices`, `addShapeModifier`

### Render

- `addToRenderQueue`, `renderQueue`, `queueInAME`
- `getRenderQueueStatus`, `clearRenderQueue`
- `exportCompFrame` - Visual verification

### Utility

- `getSelection`, `setSelection`
- `beginUndoGroup`, `endUndoGroup`, `getUndoGroupStatus`
- `getPropertyInfo`, `listFonts`

## MCP Resources

| Resource                        | Description                        |
| ------------------------------- | ---------------------------------- |
| `aftereffects://compositions`   | List all compositions              |
| `aftereffects://workflow-guide` | Visual verification workflow guide |

## Development

```bash
just setup   # Build and install CEP panel with debug mode
just build   # Build only
just start   # Start MCP server (for testing)
just clean   # Remove build directory
```

## Architecture

```
Claude Code <--stdio--> MCP Server <--WebSocket:8765--> CEP Panel <--CSInterface--> ExtendScript
```

See [ARCHITECTURE.md](ARCHITECTURE.md) for design principles.

## Project Structure

```
after-effects-mcp/
├── src/
│   ├── index.ts              # MCP server, tool definitions
│   ├── websocket-server.ts   # WebSocket server
│   ├── logger.ts             # Logging utility
│   ├── shared/
│   │   ├── commands.ts       # Command registry (single source of truth)
│   │   └── config.ts         # Configuration and timeouts
│   └── cep/                   # CEP extension
│       ├── CSXS/manifest.xml
│       ├── index.html
│       ├── js/main.js         # WebSocket client
│       └── jsx/modules/       # ExtendScript (modular)
│           ├── 00-polyfills.jsx
│           ├── 01-helpers.jsx
│           ├── 10-project.jsx
│           ├── 11-layer.jsx
│           ├── 12-keyframe.jsx
│           ├── 13-time.jsx
│           ├── 14-render.jsx
│           ├── 15-camera.jsx
│           ├── 16-mask.jsx
│           ├── 17-shape.jsx
│           ├── 18-selection.jsx
│           ├── 19-discovery.jsx
│           └── 99-dispatcher.jsx
├── scripts/
│   ├── install-cep.js
│   ├── build-jsx.ts          # Concatenates JSX modules
│   └── generate-cep-config.ts
├── tests/
├── justfile
└── package.json
```

## License

MIT