# After Effects MCP Enhanced

**[English](README.md) · [简体中文](README.zh-CN.md)**

A local [Model Context Protocol](https://modelcontextprotocol.io/) 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](https://github.com/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

| Component | Requirement / validation |
| --- | --- |
| Node.js | 22 or newer |
| Interactive editing | Licensed After Effects 2024 (24.x) or newer, running locally |
| Live validation | AE 26.2.1x2 on macOS: bridge launch, JSX, project saving, audio import, H.264 composition rendering |
| Other AE versions | Simulated bridge tests for 24.x, 25.x, 26.x and a future version; not full application certification |
| Windows | Installation discovery is tested with fixtures; live AE execution remains unverified |
| Future versions | Best effort while Adobe retains the required scripting APIs |
| Standalone rendering | An installed `aerender` able to open the saved project; implementation not yet live-tested |

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

```sh
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](skills/ae-scripting-setup/references/guide.en.md) for macOS/Windows setup, Computer Use, and connection verification. A reusable [ae-scripting-setup skill](skills/ae-scripting-setup/SKILL.md) is included.

### 2. Register your MCP server

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

```toml
[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:

```sh
node enhanced/register-codex.mjs
```

For clients using JSON configuration:

```json
{
  "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/`](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:

```sh
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

| Tool | Purpose |
| --- | --- |
| `list-installations` | Discover installed AE 2024+ versions |
| `launch-bridge` | Start the background bridge in a selected version |
| `bridge-status` | Query the connected AE version |
| `run-command` | Run predefined composition, layer, effect, keyframe, and expression operations |
| `execute-jsx` | Run arbitrary ExtendScript; return plain JSON-serializable data |
| `get-request` | Retrieve a queued request's state/result by ID |
| `import-footage` | Import a local file or image sequence; optionally add it to a composition |
| `save-project` | Save the current project to an absolute path |
| `render-composition` | Render one composition in AE while restoring other render-queue selections |
| `render-project` | Start a background `aerender` job for a saved project |
| `get-render` | Poll an `aerender` job during the current server session |

`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:

```json
{
  "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:

```sh
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

```mermaid
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

```sh
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](CONTRIBUTING.md) for contribution guidelines and [docs/UPSTREAM.md](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](LICENSE). This repository preserves the original copyright notice of **Dakkshin** and the Git history of [Dakkshin/after-effects-mcp](https://github.com/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.