# After Effects MCP Server

Local-first MCP server for controlling Adobe After Effects from Cursor or Codex through a hardened ScriptUI bridge panel.

## Designer Setup Guide

If you are setting this up as a motion designer, start here:

- `docs/designer-setup-guide.md`

## Status

This is a first-party implementation inspired by public After Effects MCP projects, but it does not vendor or run their setup scripts. The bridge protocol is intentionally narrow: tools send allowlisted commands to an After Effects panel, and the panel returns authenticated results.

## Safety Defaults

The default policy is designed for creative agent workflows while keeping higher-risk actions explicit:

- `AE_MCP_MODE=edit`: read plus basic create/edit tools are enabled.
- `AE_MCP_ALLOW_EXPRESSIONS=0`: expression editing is disabled by default.
- `AE_MCP_ALLOW_DESTRUCTIVE=0`: delete/remove tools are disabled by default.
- `AE_MCP_ALLOW_ARBITRARY_JSX=0`: arbitrary JSX execution is not exposed.
- `AE_MCP_REDACT_PATHS=1`: local paths are redacted before becoming MCP output.

Each bridge session uses a generated `sessionId` and nonce. The After Effects panel only executes commands that match the active session.

## Setup

1. Install dependencies and build:

```bash
npm install
npm run build
```

2. Install the After Effects bridge panel:

```bash
npm run install-bridge -- --dry-run
npm run install-bridge
```

The installer never invokes elevated permissions. If copying fails, follow the printed manual copy instructions.

3. Enable After Effects scripting:

- macOS: After Effects > Settings > Scripting & Expressions
- Windows: Edit > Preferences > Scripting & Expressions

Enable `Allow Scripts to Write Files and Access Network`, then restart After Effects.

4. Open the bridge panel:

- Window > mcp-bridge-auto.jsx

Keep the panel open while using Cursor or Codex.

## Cursor Or Codex Config

Copy one of the examples:

- `examples/cursor-mcp.json`
- `examples/codex-mcp.json`

Replace `<absolute-path-to-this-repo>` with your local clone path. Do not commit a user-specific config file after substituting local paths.

The server prints bridge details through the `ae_bridge_status` tool. If you set `AE_MCP_BRIDGE_DIR`, set the same directory in the bridge panel. If you do not set it, copy the generated bridge directory from `ae_bridge_status` into the panel.

## Tool Policy

Readonly mode:

```bash
AE_MCP_MODE=readonly
```

Edit mode:

```bash
AE_MCP_MODE=edit
```

Enable expressions only for trusted workflows:

```bash
AE_MCP_ALLOW_EXPRESSIONS=1
```

Enable destructive tools only when needed:

```bash
AE_MCP_ALLOW_DESTRUCTIVE=1
```

## Supported Scope

Initial supported tools:

- Project/composition/layer inspection
- Composition creation
- Text, shape, and solid layer creation
- Transform edits
- Transform keyframes
- Optional expression setting
- Optional layer deletion

Supported platforms are macOS and Windows with After Effects 2022 or later. Linux can run the Node MCP server for tests, but cannot run After Effects.

## Smoke Tests

Run automated checks:

```bash
npm test
npm run build
```

Manual After Effects smoke test:

1. Open After Effects with a throwaway project.
2. Open `mcp-bridge-auto.jsx`.
3. In Cursor or Codex, call `ae_bridge_status`.
4. Copy the reported bridge directory to the panel if needed.
5. Call `ae_get_project_info`.
6. Call `ae_create_composition` with a test name.
7. Call `ae_create_text_layer` against that composition.

If anything looks wrong, turn off the panel's auto-run checkbox. Mutating operations are wrapped in After Effects undo groups so you can undo agent mistakes.

## Development Notes

Do not run scripts from `ae-mcp-setup/`; that folder is reference material only. If borrowing behavior from upstream projects, copy only the specific reviewed function and check it for arbitrary file access, implicit active-project assumptions, alerts/prompts, destructive operations, and global state mutation.