AE Motion MCP

An MCP server that lets Claude (or any MCP client) build, animate, preview and render motion graphics in a live Adobe After Effects project.

Ask for "a 5 second lower third with an eased slide-in", and the model creates the comp, adds layers, sets keyframes, checks a preview frame and kicks off a render, all in the project you have open.

https://github.com/user-attachments/assets/8d46df59-cd4c-42e1-ab7e-8ba83552bb27

MCP client --stdio--> MCP server (Node) --HTTP 127.0.0.1 + token--> CEP panel in AE --> ExtendScript

Contents

• Requirements

• Installation

• Verify it works

• What it can do

• Configuration

• Security

• Troubleshooting

• Updates

• Updating and uninstalling

• Documentation

Related MCP server: AfterEffectsMCP

Requirements

• After Effects 2022 (22.0) or later, on macOS or Windows

• Node.js 22.18 or later (the build and tests run TypeScript directly through Node's type stripping)

• An MCP client such as Claude Code or Claude Desktop

Installation

1. Get the code and run the installer

git clone https://github.com/dha-aa/ae-motion.git
cd ae-motion

macOS:

bash scripts/install.sh

Windows (PowerShell):

./scripts/install.ps1

The installer:

1. Runs npm install && npm run build, which produces the server (dist/) and the panel's host script (panel/host/host.jsx).

2. Copies panel/ into the CEP extensions folder:

   • macOS: ~/Library/Application Support/Adobe/CEP/extensions/com.aemotion.mcp

   • Windows: %APPDATA%\Adobe\CEP\extensions\com.aemotion.mcp

3. Enables unsigned CEP panels (PlayerDebugMode, CSXS 9 to 12). This per-user setting is required for any panel that isn't signed by Adobe.

1. In the repo folder run npm install && npm run build.

2. Copy the contents of panel/ into the extensions folder above, in a folder named com.aemotion.mcp.

3. Enable unsigned panels.

   • macOS: for v in 9 10 11 12; do defaults write com.adobe.CSXS.$v PlayerDebugMode 1; done

   • Windows: for each of 9 to 12, reg add "HKCU\Software\Adobe\CSXS.<v>" /v PlayerDebugMode /t REG_SZ /d 1 /f

2. Allow scripts in After Effects

Open the preferences, go to Scripting & Expressions, and enable Allow Scripts to Write Files and Access Network.

• macOS: After Effects > Settings

• Windows: Edit > Preferences

3. Open the panel

Restart After Effects, then open Window > Extensions > AE Motion MCP and keep it open. Docking it in a workspace makes it load on startup.

The panel starts a small server on 127.0.0.1 (port 47670, or the next free port up to 47690) and writes its port and a random token to ~/.ae-motion-mcp/bridge.json. The MCP server reads that file to find it. If the panel is closed, every tool returns BRIDGE_DOWN.

4. Register the server with your client

Use the absolute path to dist/index.js.

Claude Code

claude mcp add ae-motion -- node /absolute/path/to/ae-motion/dist/index.js

Claude Desktop: add this to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\) and restart the app.

{
  "mcpServers": {
    "ae-motion": {
      "command": "node",
      "args": ["/absolute/path/to/ae-motion/dist/index.js"],
      "env": { "AE_MCP_TOOLSETS": "core" }
    }
  }
}

AE_MCP_TOOLSETS: core starts Claude Desktop with the core tools only (about 7.5k tokens of tool definitions instead of 16k on every message); the model adds 3D, timeline, masks, design or scripting with load_tools when it needs them. Leave it out to load everything. Claude Code does not need it: it loads MCP tools only when they are used.

Other clients: any client that can launch a stdio MCP server works with node /absolute/path/to/ae-motion/dist/index.js.

To set environment variables, add an env object next to args in the JSON above, or pass --env KEY=value to claude mcp add (before the server name).

Verify it works

1. The panel status line shows 127.0.0.1:<port>, and ~/.ae-motion-mcp/bridge.json exists.

2. In your client, ask: "get the project info". You should get the project's comps, footage and the After Effects version.

3. Then try something visible: "create a 1920x1080 comp at 30 fps, 5 seconds, with a white solid background, and show me frame 0".

If a call fails, the error includes a code and a hint. See Troubleshooting.

What it can do

68 tools in eleven groups. The full reference, with behavior notes, is in docs/tools.md.

Also: resources ae://project and ae://selection, and the prompt motion-guide (conventions and a recommended build loop).

Conventions: time in seconds, sizes in pixels, colors [r,g,b] floats 0 to 1, scale in percent. Comps and layers are addressed by the numeric ids tools return; properties by alias (position, scale, rotation, opacity, anchor) or an array of match names (list_properties discovers them). Every mutating call is one undo step in After Effects.

Example prompts: "orbit the camera 120 degrees around the product over 4 seconds", "cut 3s to 5s out of every layer and close the gap", "line up these five layers one after another with a 10 frame overlap", "make these cards 3D, rotate them 25 degrees and add a spot light with shadows", "center the title and give it a soft drop shadow", "space these icons evenly across the bottom".

Configuration

All settings are environment variables on the MCP server process. The one exception is AE_MCP_BRIDGE_FILE, which must also be set for the panel's environment if you change it.

Security

• The panel only listens on 127.0.0.1, and every request needs the random token stored in the bridge file, which is created readable by your user only.

• File paths passed to tools (import_footage, apply_preset, save_project, render output) must be inside AE_MCP_ALLOWED_DIRS.

• run_jsx can execute anything After Effects can, so it is off unless you opt in.

• Installing the panel turns on PlayerDebugMode for CEP, which lets this user load any unsigned panel. Turn it back off if you uninstall (see below).

Troubleshooting

Panel logs are in ~/Library/Logs/CSXS/ on macOS and %TEMP% (csxs*.log) on Windows.

Updates

You find out about new versions in three places:

• The After Effects panel shows the installed version and, when a newer release exists, a line like v2.1.0 available with an Update to v2.1.0 button.

• Your AI client: get_project (usually the first call) includes an update note with the new version and the command to run, so the model can tell you. You can also ask "check for updates" (check_for_updates).

• GitHub: releases are git tags vX.Y.Z; what changed is in CHANGELOG.md.

How the check works: the MCP server asks GitHub for the repository's version tags at most once a day, in the background, with a short timeout, and caches the answer in ~/.ae-motion-mcp/update.json (the panel only reads that file). It sends nothing but a normal anonymous request, and a failed check never affects a tool. Set AE_MCP_UPDATE_CHECK=0 to turn it off.

Updating and uninstalling

Update from the panel: click Update to vX.Y.Z (or Reinstall) in the AE Motion MCP panel, then click again to confirm. It runs git pull and the installer in your ae-motion folder, shows the output, and restarts the panel with the new version; then restart your AI client so it uses the new server. The panel finds the folder and your git / node / npm through install.json, which the installer writes, so a panel installed before this button existed needs one manual update first. If git pull fails (local changes, a branch without an upstream), update by hand.

Update by hand: in the repo folder, git pull, then run the installer again (bash scripts/install.sh, or ./scripts/install.ps1 on Windows; it rebuilds and replaces the installed panel). Reopen the AE Motion MCP panel (or restart After Effects) and restart the MCP server from your client. The panel's Version line shows the new version.

Uninstall:

1. Remove the server from your client (claude mcp remove ae-motion, or delete the entry from the Claude Desktop config).

2. Delete the installed panel folder (see Installation).

3. Delete ~/.ae-motion-mcp/.

4. Optional: turn unsigned panels back off.

   • macOS: for v in 9 10 11 12; do defaults delete com.adobe.CSXS.$v PlayerDebugMode; done

   • Windows: delete the PlayerDebugMode value under HKCU\Software\Adobe\CSXS.9 to CSXS.12.

Documentation

• docs/tools.md: every tool, the timeline and camera models, and behavior notes

• docs/architecture.md: how the pieces fit, the wire protocol, the repository layout

• docs/development.md: building, testing, adding a tool, After Effects quirks, verification status

License

MIT