# After Effects MCP

A production-grade [Model Context Protocol](https://modelcontextprotocol.io/) connector for Adobe After Effects. It gives MCP clients structured, validated control over projects, compositions, layers, properties, expressions, keyframes, imports, and the render queue—without exposing arbitrary scripting by default.

## Architecture

```text
MCP client ──stdio──> TypeScript MCP server ──authenticated localhost WebSocket──> CEP panel ──evalScript──> After Effects
```

- **MCP server:** Node.js 20+, official MCP SDK, Zod validation, stdio transport.
- **Local bridge:** loopback-only WebSocket, 256-bit shared token, request IDs, timeouts, heartbeat, one active AE session.
- **CEP extension:** reconnecting panel with serialized command execution and visible activity.
- **Host engine:** ES3-compatible ExtendScript, stable item IDs, match-name property paths, structured errors, undo groups, atomic batches.

No cloud service is involved. Project data and commands remain on the local computer.

## Features completed

- 24 MCP tools covering connection, project discovery/save/import, compositions, layers, properties, expressions, keyframes, batching, and rendering.
- Read-only/idempotent/destructive MCP annotations.
- `aftereffects://status` and `aftereffects://guide` MCP resources.
- Automatic shared config at `~/.after-effects-mcp/config.json` with owner-only permissions.
- Input limits, authenticated local transport, malformed-message handling, command timeouts, and raw scripting opt-in.
- Adobe match-name paths for locale-independent property targeting.
- One After Effects undo step per mutation; one undo step for an entire `ae_batch`.
- macOS/Windows CEP installer script and distributable ZIP packaging.
- Unit, protocol integration, and adversarial security test suites.

## Requirements

- Adobe After Effects 2020 (17.0) or newer.
- Node.js 20 or newer.
- An MCP client such as Claude Desktop, Claude Code, Cursor, or another stdio MCP host.

## Install

```bash
npm install
npm run build
npm run install:extension
```

The extension is unsigned. Enable CEP debug mode if **Window → Extensions → After Effects MCP Bridge** does not appear, then restart After Effects:

### macOS

```bash
defaults write com.adobe.CSXS.12 PlayerDebugMode 1
# Repeat with CSXS.11 or CSXS.10 when required by your Adobe version.
```

### Windows (PowerShell)

```powershell
reg add HKCU\Software\Adobe\CSXS.12 /v PlayerDebugMode /t REG_SZ /d 1 /f
```

Open **Window → Extensions → After Effects MCP Bridge** and keep the panel open. It reconnects automatically whenever the MCP server starts.

## MCP client configuration

Build output is `dist/src/server.js`. Add the following to your client's MCP configuration, replacing the absolute path:

```json
{
  "mcpServers": {
    "after-effects": {
      "command": "node",
      "args": ["/absolute/path/to/after-effects-mcp/dist/src/server.js"]
    }
  }
}
```

The `after-effects-mcp` binary is also available when the package is installed globally or linked with `npm link`.

## Tool reference

| Tool | Purpose |
|---|---|
| `ae_connection_status` | Bridge/app status and capabilities |
| `ae_project_info` | Project, selection, active item, render queue metadata |
| `ae_project_items` | Search/list project tree with stable item IDs |
| `ae_project_save` | Save or Save As |
| `ae_import_file` | Import footage, projects, or sequences |
| `ae_comp_list`, `ae_comp_get` | Discover and inspect compositions |
| `ae_comp_create`, `ae_comp_update` | Create/edit composition settings |
| `ae_layer_list` | Inspect layers and top-level property groups |
| `ae_layer_create_text`, `ae_layer_create_solid` | Create generated layers |
| `ae_layer_add_item` | Add footage/precomps to a comp |
| `ae_layer_update`, `ae_layer_duplicate`, `ae_layer_delete` | Edit layer state and ordering |
| `ae_property_get`, `ae_property_set` | Read/write any value property |
| `ae_property_keyframes` | Set keyframes and interpolation |
| `ae_property_expression` | Set/disable expressions and return expression errors |
| `ae_render_queue`, `ae_render_add`, `ae_render_start` | Render queue automation |
| `ae_batch` | Up to 100 operations in a single undo group |
| `ae_execute_script` | Optional raw ExtendScript; disabled by default |

Property path example:

```json
["ADBE Transform Group", "ADBE Position"]
```

Prefer Adobe match names (`ADBE ...`) over display names so automation works across localized After Effects installations.

## Recommended workflow

1. Call `ae_connection_status`.
2. Discover IDs with `ae_project_items` or `ae_comp_list`.
3. Read the target comp/layers/properties before writing.
4. Use `ae_batch` for related edits.
5. Inspect results, then save explicitly.

## Configuration

| Environment variable | Default | Description |
|---|---:|---|
| `MCP_AE_HOST` | `127.0.0.1` | Bridge bind address; non-loopback refused |
| `MCP_AE_PORT` | `19728` | Bridge port |
| `MCP_AE_TOKEN` | generated | Shared bridge token |
| `MCP_AE_TIMEOUT_MS` | `30000` | Per-command timeout |
| `MCP_AE_CONFIG_PATH` | `~/.after-effects-mcp/config.json` | Shared config location |
| `MCP_AE_ALLOW_RAW_SCRIPT` | `0` | Set to `1` to register raw scripting tool |
| `MCP_AE_ALLOW_REMOTE` | `0` | Explicitly allow non-loopback binding (not recommended) |

If a custom config path is used, launch the CEP host with the same `MCP_AE_CONFIG_PATH`; the standard shared path needs no setup.

## Security

- The server binds to loopback only unless two explicit overrides are provided.
- WebSocket upgrades require a constant-time verified 256-bit token.
- Raw ExtendScript is absent from the MCP tool list unless explicitly enabled.
- Curated tools use strict schemas and bounded arrays/strings.
- The CEP panel accepts commands only from its authenticated server connection.
- Rendering and layer deletion are marked destructive for compatible MCP clients.

Treat raw scripting as equivalent to running code under your After Effects user account.

## Development and testing

```bash
npm run typecheck
npm run lint
npm run test:unit          # round 1
npm run test:integration   # round 2
npm run test:adversarial   # round 3
npm run build
npm run package:extension
```

`npm run verify` runs the complete validation pipeline. The ZIP is emitted at `release/after-effects-mcp-cep.zip`.

## Entry points

- MCP executable: `dist/src/server.js` (stdio; no HTTP URI)
- Bridge WebSocket: `ws://127.0.0.1:19728/bridge?token=…`
- Local health check: `http://127.0.0.1:19728/health`
- CEP panel menu: `Window → Extensions → After Effects MCP Bridge`

## Data/storage

No database is used. The only persistent data is the local bridge config file. After Effects project mutations are applied through Adobe's scripting API and remain undoable until the project is saved/closed.

## Not implemented / platform constraints

- A signed ZXP installer is not included; signing requires a publisher certificate.
- Live end-to-end execution inside a licensed After Effects GUI cannot run in headless CI. The mock AE bridge validates protocol behavior; host-script execution should also be smoke-tested in each supported AE release.
- Dynamic Graph, Essential Graphics, Mocha, and third-party plug-in-specific APIs are reachable through property paths or optional raw scripting but do not have dedicated tools yet.

## Recommended next steps

1. Sign the CEP package for managed enterprise distribution.
2. Add AE-version matrix smoke tests on dedicated macOS/Windows workstations.
3. Add dedicated tools for masks, effects, markers, cameras/lights, and Essential Graphics based on production needs.

## Deployment status

This is a local desktop connector, not a Cloudflare/web deployment. Version 1.0.0 is buildable and packageable from the repository.