Ae MCP

ae-mcp

English | 简体中文

Automatic setup: paste this prompt into the MCP client you want to use

Install and configure ae-mcp for the current client receiving and executing

this prompt. Do not default to Claude Code or configure another client. Before changing anything, inspect the local ae-mcp extension and native plug-in files and versions, plus this client's existing MCP registration and actual connection, read-only. Existence alone does not prove readiness. Compare with the latest official stable release assets available for my platform:

• Client registration already correct: keep it; install only missing or damaged files.
• Files complete and versions suitable: only add or repair client registration.
• Both ready and current: verify without reinstalling.
• Newer version available: upgrade existing components, preserving user settings and other MCP configuration; do not downgrade. If versions cannot be established or platform assets are unavailable, explain rather than blindly overwrite.

Use the release ZXP and platform-native plug-in for needed file installation or upgrade, then open Window > Extensions > ae-mcp in After Effects. Identify this client's configuration method and location, preserving all other MCP entries. Use http://127.0.0.1:11488/mcp if it supports Streamable HTTP; for stdio only, configure npx -y ae-mcp-jkdg using this client's format. If automatic editing is unavailable, give precise manual steps for this client. Ask which client only if the target truly cannot be identified; never silently fall back to Claude Code. Keep the AE panel open, refresh/reconnect or start a new session as this client requires, then call ae_status to verify. If user action is required first, state that verification is still pending.

Let AI read your After Effects project, build animations, inspect the results, and save successful operations as reusable tools.

ae-mcp is an open-source CEP extension that connects a running After Effects project to the Model Context Protocol (MCP). Chat with Claude, Codex, or OpenCode inside the panel, or connect an external MCP client to work with compositions, layers, keyframes, and expressions.

Download v0.11.1 · Install · Tool reference · Changelog

What it does

• Read real project state: inspect projects, compositions, layers, properties, and keyframes with pagination, sorting, and filtering.
• Build and edit animations: run ExtendScript for general AE operations; use native AEGP tools for exact time and object locators.
• Inspect composition pixels: export PNG frames from AE, sample multiple times in a grid, and compare A/B pixel differences.
• Recover failed operations: use checkpoints of saved projects, captured failure scripts, and a recoveryId to inspect, correct, or restore state.
• Keep reusable tools: successful scripts become replayable candidates that can be saved, pinned, archived, exported, and imported; prompt skills are supported too.
• Follow execution: use the panel's approvals, activity timeline, conversation history, and diagnostic export.

The workflow is read → execute → preview → correct → save for reuse. The AI reads current state through the AE host, including unsaved changes, and checks results using both project structure and composition previews.

A complete workflow

Try a task like this in a test project:

Create a new composition with the text Hello AE. Over one second, fade it in

and move it upward into the center. Read back the keyframes, then check the animation with a multi-frame preview.

The screenshots show task entry, a six-frame preview, and the successful script captured in the Tool Library. These are actual v0.10.7 screens illustrating the workflow; v0.11.0 additions are described below.

Describe the task Inspect the result Keep a reusable tool

What's new in v0.11.1

• Fix native Codex image preview, zoom and conversation history.
• Improve external MCP guidance, Tool Library scanning and Windows AE process discovery/retry.
• Windows and macOS native plug-ins remain at 0.11.0; existing users only need to update the ZXP manually.

What's new in v0.11.0

• Multiple instances and parallel previews: external clients can discover, launch, and route to multiple AE instances. Different projects can run concurrently; each project has one active writer, while read-only workers inspect and preview fixed checkpoint snapshots.
• Session handoff: after a panel turn or external AE call finishes, another eligible session can take over the idle project. In-flight calls, engine draining, and uncertain writes continue to block handoff.
• AI working directory: new chats default to the current AEP's folder, falling back to the user home folder if the project is unsaved or the directory is not writable. Choose a folder or restore the default in Settings; existing chats retain their directory.
• Undo and recovery fixes: fixes for mismatched Undo groups and checkpoint recovery contexts. Rendering must run separately, outside an Undo group.
• Native and worker reliability: improved cold-start native diagnosis, connection timeout recovery, and Windows background worker startup and shutdown cleanup.
• 16 public tools, up from 13: adds ae_instances, ae_workspace, and ae_readJob, with the matching ae-mcp-jkdg@0.11.0 stdio connector.

The release provides a shared Windows/macOS ZXP, native plug-ins for Windows x64 and macOS arm64, and checksums. The final Mac package completed scoped read/write, Undo, rendering, recovery, and installation checks on AE 26.3x87 arm64. Mac worker scenarios remain unverified. See the v0.11.0 release notes for verification scope and known limitations.

Install and first run

1. Download and install ae-mcp-panel-v0.11.1.zxp from the v0.11.1 release.
2. For ae_nativeExec, download the native plug-in from the same release: AeMcpNative-v0.11.0-windows-x64.aex for Windows x64, or AeMcpNative-v0.11.0-macos-arm64.plugin.zip for macOS arm64. Extract the Mac ZIP and install AeMcpNative.plugin. Native plug-ins ship separately from the ZXP; see Install for destinations and macOS download quarantine handling. The Mac package requires macOS 14.0 or later. Both platforms use the same roughly 60 MB ZXP, which includes the Windows OpenCode runtime; macOS uses OpenCode from PATH.
3. Start After Effects and open Window > Extensions > ae-mcp. Keep the panel open while an external client uses MCP.
4. Configure Claude, Codex, or OpenCode in panel Settings, or connect an external client as described below.

The panel itself is the MCP service. No separate repository server is needed. External clients must run on the same machine as After Effects because the default endpoint is loopback.

Client connections

For one running panel, clients supporting Streamable HTTP can connect to the URL shown in the panel. For example, Claude Code with the default address:

claude mcp add --transport http ae http://127.0.0.1:11488/mcp

For instance discovery and launch, or a stdio client such as Claude Desktop, use the matching connector (requires Node.js 18 or later):

{

"mcpServers": { "ae": { "command": "npx", "args": ["-y", "ae-mcp-jkdg@0.11.0"] } } }

Without an explicit URL, the connector discovers the installed extension's multi-instance entry. It does not install or update the extension. Discover or explicitly start an instance with ae_instances, bind the project with ae_workspace, and pass the returned context_id on subsequent AE calls. Setting --url or AE_MCP_HTTP_URL pins forwarding to one endpoint. Closing the panel is an intentional disconnect and does not automatically reopen AE.

Alternatively, run the dependency-free stdio shim shipped in the installed extension. This example pins one endpoint. Set command to system Node and point args at the extension directory's host/stdio-shim.js:

{

"mcpServers": { "ae": { "command": "node", "args": [" /host/stdio-shim.js"], "env": { "AE_MCP_HTTP_URL": "http://127.0.0.1:11488/mcp" } } } }

Refresh or reconnect the client after setup, then call ae_status to verify.

How it works

The MCP service runs directly in the CEP panel's Node host, at http://127.0.0.1:11488/mcp by default. Additional instances register their own endpoints. The host manages approvals, project contexts, the Tool Library, and logs.

flowchart TB

panel["In-panel AI chat"] --> host["CEP Node MCP host"] client["External MCP client"] -->|"HTTP / stdio connector"| host

host --> jsx["ExtendScript"] host --> native["AEGP"] host --> worker["Read-only workers"]

jsx --> project["AE project reads / writes"] native --> precision["Exact time and object locators"] worker -->|"Checkpoint snapshot"| preview["Reads and PNG previews"]

ExtendScript handles general operations. The native AEGP plane retains 23 fixed primitives for exact rational time and generation-bound object locators. Multiple instances do not permit simultaneous writers to the same project; worker results always describe their specified checkpoint snapshot. See Architecture for details.

Panel capabilities

The CEP host advertises 16 public MCP tools:

Successful ae_exec and ae_execRecover scripts are captured as deduplicated, rerunnable Tool Library candidates. ae_toolSave promotes or creates reusable JSX and prompt-skill artifacts; the Tools page manages candidates and saved artifacts, including import/export. Usage counters and funnel events show what gets replayed or retained, while the placeholder guard points compacted conversations back to exact candidates and stops repeated placeholder retries.

The panel also provides approval modes, activity history, diagnostics, log export, and built-in Claude, Codex, and OpenCode channels. Persistent host state defaults to ~/.ae-mcp; developers and tests can relocate it with AE_MCP_STATE_DIR.

The public MCP tools are served by the CEP host. Writes should be followed by an independent readback; potentially side-effecting failures must be reconcil