After Effects MCP Enhanced

English · 简体中文

A local Model Context Protocol server for Adobe After Effects. Create compositions, execute ExtendScript, import footage, save projects, and render through an MCP client such as Codex.

Designed for After Effects 2024+ on macOS and Windows. Live-tested on After Effects 26.2.1 (macOS). MIT licensed; derived from Dakkshin/after-effects-mcp.

What changed

• Durable requests: separate files and unique IDs replace the upstream single command slot. Concurrent clients cannot overwrite each other's queued requests.

• Actual JSX execution: execute-jsx accepts an ExtendScript function body, not just a predefined command name.

• No persistent panel: launch the background script once per AE session, or install it as a Startup script.

• Import and render tools: local footage/image sequences, project saving, composition rendering, and standalone aerender jobs.

• Version discovery: finds 2024 and newer installations without a fixed upper-year list.

• Correlated results: get completion/error details for a specific request; slow operations return a request ID to poll.

Requirements and compatibility

A running AE application is still required for editing. aerender renders saved projects without the interactive bridge; it does not provide headless editing. The MCP's compatibility target does not make .aep files backward-compatible with older AE releases.

Quick start

git clone https://github.com/ku1x/after-effects-mcp-enhanced.git
cd after-effects-mcp-enhanced
npm ci
npm run build

npm ci also builds the enhanced bridge through postinstall. The explicit build command is useful after source changes.

1. Enable scripting access in After Effects

In AE, open Settings / Preferences → Scripting & Expressions and enable Allow Scripts to Write Files and Access Network.

This setting must be changed through AE’s interface—manually or with authorized Computer Use. Adobe forbids JSX from changing this security preference.

See the step-by-step permission guide for macOS/Windows setup, Computer Use, and connection verification. A reusable ae-scripting-setup skill is included.

2. Register your MCP server

For Codex, add the following to your Codex configuration, replacing both paths with real absolute paths:

[mcp_servers.after_effects_enhanced]
command = "/ABSOLUTE/PATH/TO/node"
args = ["/ABSOLUTE/PATH/TO/after-effects-mcp-enhanced/enhanced/server.mjs"]

Alternatively, run the optional helper. It backs up the existing configuration and adds only this named server entry:

node enhanced/register-codex.mjs

For clients using JSON configuration:

{
  "mcpServers": {
    "after-effects-enhanced": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/after-effects-mcp-enhanced/enhanced/server.mjs"]
    }
  }
}

On Windows, use an absolute node.exe path if needed and forward slashes or escaped backslashes in configuration. Restart or reload the MCP client after registering it. Ready-to-edit examples are in examples/.

3. Start the bridge

Call launch-bridge from your MCP client. It selects the latest discovered AE installation; pass {"year": 2026} to select a version.

Or run File → Scripts → Run Script File in AE and choose build/ae-mcp-v2.jsx. No panel needs to remain open. Use bridge-status to verify the connection.

For automatic startup:

node enhanced/install.mjs --year 2026 --startup

Omit --year for the newest installation. --scripts-dir /path/to/Scripts supports custom locations. --all installs into all discovered versions, but run only one AE bridge instance at a time. Protected application folders may need administrator access; the installer never invokes sudo itself. launch-bridge avoids installation into those folders.

Tools

run-command preserves upstream parameter conventions. Some legacy commands use compName, others use a 1-based compIndex. New import/render/null-object operations use a stable compId, available from listCompositions.

Example: create a composition with JSX

Call execute-jsx with:

{
  "code": "var c = app.project.items.addComp('Hello MCP', 1920, 1080, 1, 5, 30); c.layers.addText(args.text); return {compId: c.id, name: c.name};",
  "parameters": {"text": "Hello, After Effects!"}
}

Code is a function body. Use args for parameters and return for the result. Prefer ES3-compatible syntax for portable ExtendScript. Return plain data, not live AE objects.

A small SDK client is included for integration checks:

node enhanced/call-tool.mjs list-installations
node enhanced/call-tool.mjs launch-bridge
node enhanced/call-tool.mjs execute-jsx examples/hello-composition.json

How it works

flowchart LR
    A[MCP client] -->|stdio| B[Node.js server]
    B --> C[Unique pending request files]
    C --> D[AE background ExtendScript]
    D --> E[Per-request result files]
    E --> B
    B --> F[aerender process]

The bridge uses the user's Documents folder under ae-mcp-bridge-v2/, with pending, running, and results subdirectories. On Windows, the server resolves the OS Documents known folder, including redirected locations.

Requests are published atomically and consumed serially. Each MCP call waits up to 10 seconds, then returns pending or running if work continues. Poll get-request with the returned ID; do not resubmit the mutation.

Practical limits and trust

• One AE application instance consumes the bridge directory. Multiple simultaneously running AE versions are not coordinated.

• An interrupted claimed request remains running with an uncertain outcome. It is not replayed automatically. Inspect the project before retrying.

• AE dialogs and rendering can pause scheduled scripts. Clear blocking dialogs; if the queue stops after a render, run launch-bridge again to resume it.

• Results persist until manually removed. There is currently no automatic retention cleanup or cancellation tool.

• execute-jsx can modify projects and access files with AE's scripting permissions. It is not sandboxed or read-only. Use trusted local MCP clients.

• Fonts, effects, codecs, and output templates depend on the installed environment. Image-sequence filename checks do not detect every existing frame.

• aerender status is held in server memory; its logs survive in render-logs. Restarting the server loses job tracking.

Development and validation

npm ci
npm run build
npm test

The nine automated tests cover a real MCP stdio handshake, tool registration, 100 concurrent requests from two clients, result correlation, restart/timeout behavior, path validation, installation discovery, and simulated AE bridge runtimes. GitHub Actions runs these tests on Linux, macOS, and Windows with Node.js 22 and 24; no Adobe installation is required for these tests.

Two local creative integration runs exercised real AE: a five-second typography animation and a 22-second brand concept with original audio. Media and personal project files are not included in this source repository.

• enhanced/: current server, bridge runtime, installer, and helpers.

• src/: preserved upstream implementation and reusable AE functions.

• test/: automated tests.

• npm run build:legacy / npm run start:legacy: original server.

See CONTRIBUTING.md for contribution guidelines and docs/UPSTREAM.md for the original documentation.

Uninstall

Remove the MCP configuration entry. If installed, remove only ae-mcp-v2.jsx from the selected AE Scripts/Startup or Scripts/ScriptUI Panels directory, then restart AE to stop the scheduled bridge. Remove the local ae-mcp-bridge-v2 directory only when its saved results are no longer needed.

License and attribution

MIT. This repository preserves the original copyright notice of Dakkshin and the Git history of Dakkshin/after-effects-mcp. The enhanced implementation and bilingual documentation are maintained in this repository. This is an independent community project, not an official Adobe product.