mcp-aftereffects

Let an LLM drive Adobe After Effects. mcp-aftereffects bridges MCP-compatible clients (Claude Desktop, Claude Code, or any other stdio-capable MCP client) to a running After Effects session so the model can inspect project state, mutate comps and layers through atomic undo-grouped operations, checkpoint and restore entire projects as JSON, and verify its own edits by rendering frames — a typed tool layer instead of ad-hoc scripts pasted into the ExtendScript console.

Good for:

• Comp audits — "List every layer in Main; flag any with a disabled effect, a missing footage reference, or an expression error."

• Keyframe / expression work — "Add eased position keyframes to layer 3 between 0s and 2s, then put a wiggle expression on its opacity."

• JSON checkpoint / restore — snapshot the whole project to a JSON document before risky changes, roll back with a single import.

• Render-verify loops — mutate, render a frame with ae_render_frame, look at the PNG, correct, repeat — the model checks its own work visually.

How it works

MCP client (Claude Code, Claude Desktop, …)
   │ stdio
   ▼
mcp-aftereffects  (Node.js)
   │ AfterFX.exe -r (Windows) / osascript (macOS)  +  file IPC
   ▼
After Effects  (your running instance)

There is nothing to install inside After Effects — no plugin, no panel, no socket. The server drives your existing AE instance — through AfterFX.exe -r on Windows, through AppleScript (osascript → DoScript) on macOS — one round trip per tool call. Every call runs inside a single automatic undo group, so one Ctrl+Z reverts exactly one call. Transport internals are documented in CONTRIBUTING.md.

Related MCP server: After Effects MCP Server

Requirements

• Windows or macOS.

• Adobe After Effects 2024, 2025, or 2026. Default install locations are probed automatically (2026 → 2025 → 2024): C:/Program Files/Adobe/Adobe After Effects <year>/Support Files/AfterFX.exe on Windows, /Applications/Adobe After Effects <year>/Adobe After Effects <year>.app on macOS. Override with AE_MCP_EXE if yours lives elsewhere.

• Node.js 24+.

• The AE preference Preferences → Scripting & Expressions → Allow Scripts to Write Files and Access Network must be ON. Without it every call times out.

• macOS only: allow Automation. The first call makes macOS ask whether your MCP client (or terminal) may control After Effects. Approve it — or later under System Settings → Privacy & Security → Automation. A denied permission shows up as calls failing fast with a Not authorized transport error.

• An MCP-compatible client (e.g. Claude Code).

Quickstart

1. Clone & build:

   git clone https://github.com/kumoproductions/mcp-aftereffects.git
   cd mcp-aftereffects
   npm install
   npm run build

2. Register with your MCP client. For Claude Code, add to your .mcp.json (use the absolute path to your checkout):

   {
     "mcpServers": {
       "aftereffects": {
         "command": "node",
         "args": ["/absolute/path/to/mcp-aftereffects/dist/index.js"]
       }
     }
   }

   Once the package is published to npm, "command": "npx", "args": ["-y", "@kumoproductions/mcp-aftereffects"] works without a local checkout.

3. Start After Effects manually and open (or create) a project. The transport targets the existing AE instance; a warm call takes ~500 ms–1 s. If AE isn't running, the first call cold-launches it (10–30 s) and is unreliable until AE has been through some user interaction — starting AE yourself first is the dependable path.

Then try:

"What comps are in this project? Add a red solid to Main and render frame 0 so I can see it."

The LLM will call ae_project_info → ae_do → ae_render_frame in sequence.

Environment variables

Capability policy

Three independent switches. ae_catalog only ever advertises what the current policy will actually execute, so the model plans against what it can run rather than concluding the server is broken.

ae_render_frame and ae_project_export_json survive read-only mode: they write files but never touch the project, and the render-verify loop is the point of an inspection session. Read that literally — read-only means "does not modify your project", not "has no side effects": both tools write to whatever absolute path they are given, so the model can still create or overwrite files anywhere After Effects can write (the one exception being the server's own IPC directory, which they refuse). The active policy is printed to stderr at startup and returned by ae_catalog.

Tools

11 tools. The LLM picks tools itself based on the prompt — you rarely invoke them directly. See docs/TOOLS.md for the generated per-tool reference.

Read-heavy work gets dedicated tools; the entire mutation surface hangs off a two-step model instead: ae_catalog enumerates atomic operations grouped by category with their parameter schemas, and ae_do executes one by name — validating arguments against the published schema before anything reaches After Effects, and returning ambient context (active comp, selection, project state) with every response. eval.run is the opt-in escape hatch when no atomic operation fits.

Usage patterns

Discovery: "what's in this project?"

1. ae_project_info() → item list and the active item.

2. ae_comp_info({ nameOrId: ["Main", "Intro"] }) → layer lists for several comps in one call.

3. ae_layer_info({ compNameOrId: "Main", layerIndex: "all" }) → every layer's full property values and keyframes in one call (a single index or an array of indices also works).

Mutation with visual verification

1. ae_catalog({ category: "layer" }) → find the operation and its params.

2. One ae_do call both mutates and verifies — batch.run children run in order, and render.frame / comp.info ride in the same call:

   ae_do({ operation: "batch.run", args: { ops: [
     { operation: "keyframe.add", args: { comp: "Main", layer: 2, property: ["Transform", "Position"], time: 0, value: [960, 540] } },
     { operation: "render.frame", args: { comp: "Main", time: 0, outPath: "/absolute/path/check.png" } }
   ] } })

3. View check.png through your client's image capability to verify the result.

4. If wrong, correct with another ae_do call — one project.undo reverts the whole previous call, batch included.

Checkpoint / restore via JSON

• Snapshot before risky changes: ae_project_export_json({ outPath: "/absolute/path/before.json" }).

• Make changes via any combination of mutating tools.

• Roll back if needed: ae_project_import_json({ inPath: "/absolute/path/before.json", clearFirst: true }).

• Validate a document without touching AE: ae_project_import_json({ inPath, dryRun: true }) returns the plan (item counts) only.

Custom JSX via eval.run

Requires AE_MCP_ENABLE_EVAL=1. ae_do({ operation: "eval.run", args: { code: "..." } }) runs an ES3 function body: var only (no let/const, arrow functions, or template strings), classic for loops, and end with return <JSON-friendly-value>;. The code already runs inside the call's automatic undo group — never open your own. Helpers are in scope under AE.* (AE.findCompByNameOrId, AE.serializeLayerFull, AE.exportProject, …) and log("message") pushes breadcrumbs into the response; ae_context returns the full helper list and rules.

Troubleshooting

• Every call times out. Check that After Effects is running with a project open, and that Preferences → Scripting & Expressions → Allow Scripts to Write Files and Access Network is ON — without it AE cannot write responses. On macOS, also check that your MCP client is allowed to control After Effects (System Settings → Privacy & Security → Automation).

• AE_NOT_FOUND. After Effects is not in the default install locations — set AE_MCP_EXE.

• AE warns "Attempt was made to run a second script while another script was already running". AE runs one script at a time and refuses any script delivered mid-run — and the warning dialog itself blocks all scripting until dismissed, so click OK first. Server-originated calls are serialized across processes by a busy lock, and a refused dispatch is retried automatically; the usual remaining causes are a user-installed panel/startup script running at that moment, or two different script-driving tools (another AE automation tool, or this server registered twice) driving the same AE — remove one.

• A call hung After Effects:

  1. taskkill /F /IM AfterFX.exe (Windows) / pkill -9 -f "Adobe After Effects" (macOS)

  2. Start AE again and open (or create) a project so it is in a "ready" state

  3. Retry

• Deeper digging: the server prints its mailbox path to stderr at startup; dispatcher.log in that directory records what each call did inside AE. A "no pending request" line there means AE and the server disagree about the mailbox location (typically AE running as a different user).

Known limitations

• Import fidelity with missing footage. ae_project_import_json addresses layers by their original stacking index. When a layer is skipped during import (its source footage is absent and no placeholder resolves), later parent-index references can point at the wrong layer. Keep the referenced footage reachable, or expect parenting to need a manual touch-up on projects with missing sources.

• One After Effects instance. Multiple MCP clients are safe, but they all drive the same AE, and AE runs JSX single-threaded. Concurrent calls queue; they do not parallelize. Use batch.run to collapse a burst of mutations into one round trip.

• Ambient context is not free in tokens. Every ae_do response carries the active comp and full selected-layer list. It costs no extra round trip, but on a comp with hundreds of selected layers it is not nothing.

• macOS support is young. The macOS launcher (AppleScript / osascript) is newer than the Windows path and has seen less real-world use. Issue reports are welcome.

Contributing

Bug reports, feature requests, and PRs are welcome. CONTRIBUTING.md covers the development setup, transport internals, testing tiers, and how to add tools and operations.

License

MIT © 2026 kumo.productions, Inc.

Trademarks

Adobe® and Adobe After Effects® are trademarks of Adobe Inc. This project is an independent, unofficial tool, not affiliated with or endorsed by Adobe.