# After Effects MCP

Let Claude and other AI agents work in Adobe After Effects: build comps, animate with keyframes and expressions, lay out and warp type, look at frames, and render, all through the [Model Context Protocol](https://modelcontextprotocol.io). It ships with **skills** that turn a short brief into a finished, sound-designed video.

<p align="center"><img src="docs/relay-demo.gif" width="720" alt="A white ball flicks a toggle, rolls a progress slider, bounces down notification cards, types 'deploy' on a keyboard and launches home while the camera reveals the whole course"></p>
<p align="center"><sub>Made end to end by an agent with the <code>ae-explainer-engaging</code> skill: real hop physics, squash and stretch, a following camera, a seamless loop and a measured sound pass. <a href="examples/relay-engaging/">How it was built</a>.</sub></p>

## What's in the box

**The MCP server**
- **115+ commands**: compositions, layers, shapes, text, masks, effects, cameras, keyframes, expressions, markers, rendering, plus procedural and layout tools.
- **Results come straight back.** Each command runs over a local socket and returns its result in the same call; `render-frame` returns a frame as an image the agent can look at.
- **Many agent sessions, one After Effects.** The first server becomes a hub and the others route through it; if it closes, another takes over.
- **Renders that don't freeze AE.** Full renders run in a separate process with `aerender`.
- **Safe timeouts.** A command that can't reach AE in time (a dialog is open, a render is running) is dropped and never runs later by surprise.

**The skills** ([`skills/`](skills/README.md)): Claude Code skills that make finished videos with the server.

| Skill | Makes |
|---|---|
| `ae-explainer-engaging` | A 10–30 s one-take story: a hero element bounces through a product's workflow with real physics and a following camera |
| `ae-explainer-high-energy` | A 12–20 s hype promo: beat-locked kinetic type, a shape that carries every transition |
| `ae-explainer-default` | A clean 45–90 s product demo with the product's UI rebuilt as vector layers |
| `ae-motion-broll` | Motion-graphic B-roll for a talking-head video, timed to the speaker's words |
| `ae-sound-effects` | A measured sound pass: cues from comp markers, beat grid checked, CC0 sounds, mixed to −16 LUFS |
| `ae-object-separation` | Subject cut-outs from footage with SAM 2, as After Effects track mattes |
| `ae-motion-core` | The foundation they share: a tested expression library (springs, ballistic hops, squash and stretch, camera follow, typing) and a build, check and render workflow |

## Quick start

You need After Effects 2022 or later (developed on 2026, macOS), Node.js 18+, and an MCP client such as Claude Code or Claude Desktop.

**1. Install the server and the After Effects panel**

On macOS double-click `Install AE MCP (Mac).command`, on Windows `Install AE MCP (Windows).bat`. It builds the server, copies the bridge panel into After Effects (asking for your admin password if needed) and registers the server as `after-effects` in Claude Desktop. Or by hand:

```bash
git clone https://github.com/pouulll/after-effects-mcp-extended.git
cd after-effects-mcp-extended
npm install              # also builds
npm run install-bridge   # copies the panel into After Effects
```

and register it with your client, for example in Claude Code:

```bash
claude mcp add after-effects -- node "$PWD/build/index.js"
```

**2. Open the panel in After Effects**

Enable **Settings → Scripting & Expressions → Allow Scripts to Write Files and Access Network** (Windows: **Edit → Preferences**), restart After Effects, and open **Window → mcp-bridge-auto.jsx**. It should read **Connected to MCP server (port 8790)**.

**3. Install the skills** (optional)

```bash
cp -R skills/ae-* ~/.claude/skills/
```

Then ask your agent something like *"Make a 12-second engaging explainer for my app"*, or just *"run bridge-status"* to check the connection.

## How it works

```
 Claude session A ── MCP server (hub) ◄──────── TCP 127.0.0.1:8790 ──────── After Effects
 Claude session B ── MCP server (follower) ──┘                              (bridge panel)
```

After Effects doesn't let scripts listen on sockets, so the **bridge panel** inside AE connects *out* to the MCP server and polls it for work every 40–120 ms. Every agent session starts its own copy of the server; the first becomes the **hub** (it owns the panel connection and a single command queue), later ones become **followers** that forward their calls through it, and if the hub's session closes a follower takes over within about a second. Every command carries a deadline, so nothing runs late after its caller has given up.

## Tools

| Tool | What it does |
|---|---|
| `run-script` | Runs any of the 115+ commands and returns its result |
| `bridge-status` | `connected`, `busy` (AE is rendering or blocked by a dialog) or `disconnected`, plus AE version, round-trip time and hub/follower role |
| `render-frame` | Renders one frame and returns it as an image. Areas with no layer are transparent |
| `start-render` | Renders the render queue in the background with `aerender`; returns a job id |
| `render-status` / `cancel-render` | Follows or stops a background render |
| `create-composition` | Typed shortcut for creating a comp |
| `get-help` | Usage guide for agents |

```
run-script { script: "createTextLayer", parameters: { compName: "Intro", text: "Hello", fontSize: 96 } }
```

### Command highlights

| Area | Commands |
|---|---|
| Project | `getProjectInfo`, `listProjectItems`, `importFootage`, `saveProject`, `openProject`, `projectCleanup` |
| Comps | `createComposition`, `duplicateCompositionDeep`, `precompose`, `updateCompSettings`, `setActiveComposition` |
| Layers | text, shape, solid, null, camera and light layers; `setLayerParent`, `moveLayer`, `splitLayer`, `setLayerSwitches` |
| Properties | `getProperty`, `setPropertyValue`, `searchProperties`, `getLayerProperties`; any property by path, e.g. `"Contents/Rectangle 1/Rectangle Path 1/Size"` |
| Animation | `setKeyframes`, `getKeyframes`, `quantizeKeyframes`, `staggerLayers`, `applyValueCurve`, `bpmMarkers` |
| Expressions | `setExpressionByPath`, `listExpressions`, `getExpressionErrors`, `bakeExpression`, `sampleProperty` |
| Text layout | `layoutTextStack` (type-scale hierarchy fitted to the layout), `fitTextToBox`, `alignLayers`, `distributeLayers`, `setAnchorPoint`, `warpText`, `textOnPath` |
| Effects & text | `applyEffect`, `applyEffectTemplate`, `setTextProperties`, `textAnimatorPreset`, `applyMotionPreset` |
| Procedural | `generatePath`, `proceduralLayout`, `scatter3D`, `makeVariations`, `applyPalette`, `cameraRigPreset`, `setupDOF` |
| Rendering | `addToRenderQueue`, `listRenderQueue`, `startRender`, `renderFrames`, `saveFrameToPng`, `exportMogrt` |
| Efficiency | `batch` (many commands in one call and one undo step), `buildComposition` (a whole comp in one call) |
| Escape hatch | `evalScript` runs arbitrary ExtendScript |

The full reference is in [CAPABILITIES.md](CAPABILITIES.md). Every command that changes the project is one undo step in After Effects.

### Text layout

These commands measure what is actually on screen, so parenting, scale and rotation are handled.

- **`layoutTextStack`** sizes a title, subtitle and body on a modular type scale, stacks them with consistent gaps and scales the whole block to fit the area (title-safe by default).
- **`fitTextToBox`** finds the font size at which text fits a box, the comp or another layer, then aligns it inside.
- **`alignLayers`**, **`distributeLayers`** and **`setAnchorPoint`** work like AE's Align panel, plus safe areas, boxes and target layers.
- **`warpText`** applies Photoshop-style warps (arc, bulge, flag, wave, rise, …). It first wraps the text in a precomp sized to the text, because AE's warp effects otherwise bend the whole comp-sized text layer and skew the type. The text stays editable.
- **`textOnPath`** puts text on an arc, circle, wave or your own curve with AE's Path Options, so glyphs stay sharp and upright.

### Background rendering

`start-render` hands the render queue to `aerender`, which renders the **saved** project in its own After Effects process while yours stays usable (pass `saveProject: true` to save first). Follow it with `render-status`. `inProcess: true` renders inside AE instead, `queueInAME: true` sends the queue to Media Encoder, and `AE_RENDER_PATH` points at `aerender` if it isn't found automatically.

## Example

[`examples/relay-engaging/`](examples/relay-engaging/) is the video at the top: one `build.jsx` that builds the whole project (rebuild it in seconds through `evalScript`), the expressions it uses, and what was measured along the way.

## Companion tools

`tools/frame_tools.py` makes contact sheets, frame metrics, visual diffs and GIF previews from rendered frames (needs Pillow). `tools/audio_tools.py` extracts amplitude envelopes, onsets and BPM from audio, ready for `applyValueCurve` and `bpmMarkers` (needs numpy and ffmpeg).

## Troubleshooting

| Symptom | What to check |
|---|---|
| `bridge-status` says `disconnected` | Is the panel open, and is **Accept commands** checked? Click **Reconnect to MCP Server** in the panel |
| `bridge-status` says `busy` | AE is rendering or showing a dialog. Close the dialog; queued commands continue |
| Panel says "Waiting for MCP server…" | No MCP client is running the server. Start Claude or your client |
| Panel can't connect at all | Check **Allow Scripts to Write Files and Access Network**. Run `src/scripts/diagnose-socket.jsx` via **File → Scripts → Run Script File** to test sockets |
| Port 8790 is taken | The server falls back to 8791–8794 and writes the port to `~/Documents/ae-mcp-bridge/port.json`, which the panel reads. `AE_MCP_PORT` forces a port |

## Security

The server only listens on `127.0.0.1`, but anything on your machine that can reach that port can run commands in After Effects, including `evalScript`, which runs arbitrary ExtendScript. Use it on a machine you trust.

## Development

```bash
npm run build   # bundles src/index.ts with esbuild and copies src/scripts → build/scripts
```

| Path | Contents |
|---|---|
| `src/index.ts` | MCP server: tools, bridge hub/follower, aerender jobs |
| `src/scripts/mcp-bridge-auto.jsx` | The After Effects panel (ExtendScript, ES3) |
| `src/scripts/commands.jsx` | Hot-reloadable command pack, synced to `~/Documents/ae-mcp-bridge/` and reloaded by the panel when it changes |
| `src/scripts/commands-manifest.json` | Pack commands that `run-script` allows |
| `skills/` | The Claude Code skills |
| `setup.js`, `install-bridge.js` | Installers |

Panel changes need a reinstall (`npm run install-bridge`) and an After Effects restart; `commands.jsx` changes only need a server restart.

## Credits

Started as a fork of [Dakkshin/after-effects-mcp](https://github.com/Dakkshin/after-effects-mcp); the socket bridge, multi-session hub, command pack, background rendering and most of the server have since been rewritten, and the original layer and composition commands still live in the panel. The skills adapt the video styles of Bart's [motion-graphics](https://github.com/Barty-Bart/motion-graphics) skills (MIT; see [`skills/LICENSE-motion-graphics.md`](skills/LICENSE-motion-graphics.md)); the sound-pass method is by Vox ([@Voxyz_ai](https://x.com/Voxyz_ai/status/2109358372873183564)).

## License

MIT. See [LICENSE](LICENSE).