ae-mcp

English | 简体中文

ae-mcp is a backend-agnostic automation tool that keeps Adobe After Effects and AI agents in the same working context. Its MCP server exposes AE project state, tool execution, previews, screenshots, and checkpoints so an agent can understand and operate the current AE project during a conversation.

The MCP server is the core. Outside the MCP layer, ae-mcp also ships a CEP panel that wraps built-in agent chat, backend configuration, approval controls, diagnostics, and first-run setup. You can use ae-mcp from an external agent backend through MCP, or configure Claude / Codex / ZCode directly inside the AE panel.

v0.9.2 is the Windows x64 release. macOS compatibility, bundled RuntimeManager, the production cross-platform signing chain, and the complete AE 25/26 hardware matrix move to v0.9.3.

v0.9.2 Target Support Matrix

The published v0.9.2 asset targets this verified release scope:

• Windows 11 24H2 (11.0.26100) or newer on x64. Windows on ARM is not supported.

• After Effects 25.x is hardware-validated. The CEP manifest remains [25.0,26.9]; complete AE 26 and macOS acceptance is deferred to v0.9.3.

Related MCP server: After Effects MCP

Architecture

Embedded panel chat or external MCP client
  -> packages/core (ae_mcp, Python stdio MCP server, 16 public tools)
  -> backend (packages/bridge, httpx)
  -> CEP panel Node host (plugin/host, Express, 127.0.0.1:11488)
     -> native RPC -> AEGP main-thread dispatcher
     -> CSInterface.evalScript -> ExtendScript (`ae_exec`)
  -> After Effects

ae_previewFrame remains the AE-internal CompItem.saveFrameToPng path for rendering real comp pixels, with viewer snapshot only as a fallback. packages/snapshot-mss provides Windows ae_snapshot screen capture through the mss backend.

The MCP core is backend-agnostic: external clients can talk to AE through the stdio server, while the CEP panel can also host built-in agent chat. The existing panel layer handles backend setup, approvals, diagnostics, and activity history. The published v0.9.2 Windows asset predates bundled-runtime activation; current v0.9.3 macOS development includes a panel RuntimeManager that verifies, installs, atomically activates, repairs, rolls back, and uninstalls the packaged runtime without using an online package manager. Claude, Codex, and ZCode are built-in panel backends; OpenCode and other tools can still connect as external MCP clients.

v0.9.2 Release Candidate Scope

• One protected main candidate SHA produces both native platform payloads; a failed or changed candidate must be rebuilt under a new SHA.

• Core operation is designed to be offline and self-contained in the signed release payload. System Python, system Node, uv, PyPI, and npm resolution are development inputs, not normal-user install prerequisites.

• Provider, Tool Library, and Platform Helper implementation is complete, including Windows AE 2025 hardware validation. v0.9.2 ships a self-signed Windows ZXP whose certificate is valid until 2037; the asset has no TSA timestamp, and its native Helper binaries are not Authenticode-signed. Bundled RuntimeManager, production native signing, macOS, and the remaining hardware cells are v0.9.3 work.

• UXP, Intel Mac, Windows ARM, provider-config export, and ZCode desktop captcha/runtime-header bridging are outside the v0.9.2 support scope.

Install and First Run

Normal users install one immutable asset from the v0.9.2 release set. Do not use source archives or an online uv/PyPI install as a substitute for a signed release asset:

Install ae-mcp-panel-v0.9.2-windows-x64.zxp with a supported ZXP installer, restart After Effects, and open Window -> Extensions -> ae-mcp. This release retains the existing external runtime setup; the bundled offline RuntimeManager is deferred to v0.9.3.

The GitHub Release publishes the exact Windows asset and its SHA-256 digest. See Install and Release.

Built-in Backends

Claude Code CLI is separate from Claude Desktop. Claude Desktop MCP configuration is not reused by the embedded Claude backend. Codex has the same distinction: the panel either talks to Codex CLI state or to providers configured for ae-mcp.

Panel Features

• Built-in chat with Claude, Codex, and ZCode.

• Composer controls for model selection, reasoning effort, fast mode, and approval mode. Model switching is session-local and does not clear the conversation.

• Four approval modes: read-only, manual, auto, and bypass. Tool annotations drive consistent behavior across backends; destructive/external Tool Library plans remain interactive even in bypass mode.

• Unified Provider Manager with expandable editable records for OpenAI-compatible and Anthropic providers.

• Activity stream for agent operations.

• Local Tools library for generated JSX, expressions, prompt skills, recipes, and diagnostics. Index/search responses stay summary-only; full content appears only after Inspect.

• Kill switch to stop all AI operations immediately.

• Current diagnostics cover host status, access token, Python client signal, AE project state, ExtendScript ping, optional channel CLIs, and verified RuntimeManager state on macOS development builds.

• Log export for issue reports and debugging.

• AE expert guidance injection. This optional setting adds AE command and data-structure guidance to reduce scripting mistakes at the cost of extra prompt tokens.

Screenshots

External MCP Clients

The v0.9.3 macOS panel-generated MCP config for external clients has this shape:

{
  "mcpServers": {
    "ae": {
      "command": "/Users/<USER>/.ae-mcp/bin/ae-mcp",
      "env": {
        "AE_MCP_BACKEND": "ae-mcp",
        "AE_MCP_PLUGIN_URL": "http://127.0.0.1:11488"
      }
    }
  }
}

This is the stable-launcher contract. On macOS the Panel now emits the expanded absolute launcher path and never resolves ae-mcp from bare PATH; the RuntimeManager verifies and activates the packaged runtime before the launcher is used. Windows v0.9.2 behavior remains unchanged in this implementation. See RuntimeManager.

External clients must run on the same machine as After Effects, or otherwise be able to reach 127.0.0.1:11488 on the AE machine. This matters for long-running or Dockerized IM-bot frameworks such as OpenClaw and AstrBot.

Tool Surface

ae_exec is the default route for maintained ExtendScript semantics. ae_nativeExec accepts only generated curated AEGP primitives. Load builtin:skill:ae-execution-guide for routing, program composition, readback, uncertain-write reconciliation, and real Undo verification.

Native programs contain at most 64 ordered operations. Values saved by resolver operations are request-local; use stable locators to resolve again in a later request. Writes require operationKey and undoGroup, then an independent readback. Do not retry a possibly-side-effecting result before reconciling AE state and audit evidence.

Inspect the generated primitive catalog in native/ae-plugin/protocol/native-primitives.json, or load the default execution guide through the Skill library. The four Tool Library calls follow progressive disclosure: Index, Search, Inspect, then Use.

Usage Notes

AI is not a finished-motion-design replacement. ae-mcp works best when you keep creative direction, taste, and final compositing judgment in human hands, while delegating repetitive operations, procedural animation, expression work, project cleanup, and refactoring of reusable AE structures.

For visual work, ask the agent to preview frames and verify intermediate results. For larger edits, create checkpoints so the project can return to a known good state.

Development

Close every After Effects / AfterFX process before a development deployment. The CEP installer preflights and stages the panel with its own backup flow. The native AEGP installer described below independently verifies its artifact and returns a transaction ID for exact rollback.

Native AEGP SDK input

The Adobe After Effects C/C++ Plug-in SDK is not distributed with this repository and is never downloaded automatically. Developers must obtain the matching SDK from Adobe's official After Effects Developer page using Get the SDKs, then extract it outside this checkout. The current native input lock is After Effects SDK 25.6, build 61, 64-bit:

Point AE_SDK_ROOT at the local extracted ae25.6_61.64bit.AfterEffectsSDK directory (or its direct parent), and point AE_SDK_ARCHIVE at the original outer archive. Before any native build, verify both the archive identity and extracted layout/content:

export AE_SDK_ARCHIVE=/absolute/path/AfterEffectsSDK_25.6_61_mac.zip
export AE_SDK_ROOT=/absolute/path/ae25.6_61.64bit.AfterEffectsSDK
node scripts/package/ae-sdk-input.mjs verify-input --platform macos-arm64

Use windows-x64 for the Windows input. The validator fails clearly with AE_SDK_ROOT_REQUIRED/AE_SDK_ARCHIVE_REQUIRED when input is missing, AE_SDK_ARCHIVE_INVALID for the wrong archive bytes, AE_SDK_LAYOUT_INVALID for a wrong or changed extraction, and AE_SDK_CONTENT_EVIDENCE_PENDING when a platform does not yet have a reviewed canonical content lock. Windows root content evidence is currently pending and therefore fails closed.

Never commit the SDK archive, headers, examples, PDFs, PiPLtool, or package-bundled extraction scripts/binaries to GitHub or Git LFS. Public CI contains only a guard that rejects vendored SDK material; it never receives the SDK. Read the complete SDK intake, verification, and distribution policy.

Build and install the native AEGP host on macOS

This development flow is separate from the CEP panel installer below. It currently builds only an Apple Silicon arm64 AEGP host. Commit the product source first: evidence builds fail closed with AE_PLUGIN_SOURCE_DIRTY unless the entire worktree is clean, so the receipt can identify the native component source. To prevent bypassing the transactional installer, the output path must be a new absolute directory under canonical /private/tmp; it must remain outside every Git worktree, the Git common directory, and the SDK root.

BUILD_DIR=/private/tmp/ae-mcp-native-73
node native/ae-plugin/build-macos.mjs \
  --sdk-archive "$AE_SDK_ARCHIVE" \
  --sdk-root "$AE_SDK_ROOT" \
  --output "$BUILD_DIR"
node native/ae-plugin/verify-macos.mjs \
  --bundle "$BUILD_DIR/AeMcpNative.plugin"

The current native implementation checks the local user, After Effects process ancestry, endpoint, and peer identity. These are compatibility-era implementation details, not a supported defense against another local account or hostile same-user code. The product trust boundary is one trusted user operating AE and selected clients on the same host; there is no connection code or fingerprint ceremony. Do not add remote, multi-user, pairing, or hostile-local-process gates without a new product decision. Provider/API secret confidentiality remains required; see the product trust policy.

Close every After Effects, AfterFX, and aerender process before installing. The development installer validates the receipt shape, product version, protocol metadata, platform, architecture, entrypoint, signature, and installed copy, and installs the loadable bundle at ~/Library/Application Support/Adobe/Common/Plug-ins/7.0/MediaCore/ae-mcp/AeMcpNative.plugin:

node native/ae-plugin/install-dev-macos.mjs install \
  --artifact-dir "$BUILD_DIR"

The default development identity profile records source revisions but does not reject an otherwise compatible locally built artifact only because its source commit or recorded payload hashes differ. Product-version equality remains required because no compatibility range exists. Use --profile release-audit for an explicit exact-source, exact-receipt, and exact-artifact audit; release workflows select that profile themselves.

That MediaCore namespace is kept strict: it is either empty during a transaction or contains only the active AeMcpNative.plugin. Transaction records and every complete stage, backup, failed, or replaced bundle live outside Adobe's scan roots under ~/Library/Application Support/AfterEffectsMCP/native-plugin-dev-v1/. With AE closed, the installer moves the complete legacy namespace into an off-scan quarantine, restores only the active bundle, and resumes safely from interrupted migration boundaries. A .disabled suffix alone is not treated as a safe isolation boundary. Recoverable metadata or staging remnants from an interrupted write are preserved under the same state root's orphan-evidence/; if deployment evidence references an incomplete record, recovery fails closed instead of guessing.

A persistent Darwin kernel guard serializes install, recovery, and rollback, including stale-owner recovery. Do not run this installer concurrently from an older checkout: observed live legacy locks are rejected, but cross-version installers do not share the new guard protocol.

Keep the returned transactionId. With AE closed, roll back exactly that current transaction:

TRANSACTION_ID="paste the transactionId from the install output here"
node native/ae-plugin/install-dev-macos.mjs rollback \
  --transaction "$TRANSACTION_ID"

If a previous installer process was interrupted between transaction phases, keep AE closed and reconcile its durable record before retrying:

node native/ae-plugin/install-dev-macos.mjs recover

Ad-hoc signing and a successful local build are development evidence only. The generated receipt deliberately keeps distributionApproved, runtimeEvidence, and compatibilityEvidence false; each candidate still requires a recorded component-set real-AE gate through the public MCP surface.

The public AE execution surface has two routes. Use ae_exec for maintained After Effects scripting-object-model operations. Use ae_nativeExec only for curated AEGP primitives that require exact native graph, time, ratio, or property semantics. Load builtin:skill:ae-execution-guide before composing a non-trivial request.

A native request is one bounded linear operations array. Resolver operations create typed request-local handles; later operations refer to them with {"ref":"name"}. Handles never serialize and never survive a request, so every later request resolves fresh handles from stable locators. Read programs omit operationKey and undoGroup. A program containing a write requires both, runs inside one real AE Undo group, and is not advertised as atomic.

Verify every write with an independent read. A possibly-side-effecting result must be reconciled against AE state and audit evidence before any retry. Undo availability is not Undo verification: execute real Undo and run another independent read to prove restoration.

The generated primitive reference is bundled into the execution guide. The sole hand-maintained catalog is native/ae-plugin/protocol/native-primitives.json; validate generated projections with uv run python scripts/generate_native_exec.py --check.

CEP panel macOS development setup:

uv sync --all-packages --group dev
(cd plugin/host && npm ci)
(cd plugin/sidecar && npm ci)
(cd plugin/panel && npm ci && npm run build)
./scripts/install-plugin-dev-macos.sh

Windows development setup:

uv sync --all-packages --group dev
cd plugin\host
npm ci
cd ..\sidecar
npm ci
cd ..\panel
npm ci
npm run build
cd ..\..
.\scripts\install-plugin-dev.ps1

Test

Non-live:

uv run pytest

Live, with AE open and the ae-mcp panel running:

$env:AE_MCP_LIVE_TESTS = "1"
$env:AE_MCP_BACKEND = "ae-mcp"
$env:AE_MCP_PLUGIN_URL = "http://127.0.0.1:11488"
uv run pytest packages/core/tests/live -o addopts='' -vv

Model-matrix smoke for Claude sidecar + Codex app-server:

node scripts/live-model-matrix.mjs

Package and Release

Maintainers create v0.9.2 artifacts only through the protected build-rc.yml workflow. The exact Mac arm64 and Windows x64 bytes are bound to artifact-manifest-v0.9.2.json, validated by macos-rc-attestation and windows-rc-attestation, then promoted by release.yml without rebuilding. Signing credentials, redistribution approvals, AE 25/26 installations, and a Windows x64 verifier are external prerequisites; see docs/RELEASE.md.

Implementation Notes

Third-party components:

• plugin/client/CSInterface.js is Adobe CEP CSInterface v11 and retains Adobe's original license notice in that file.

• ae-mcp-snapshot-mss uses mss and Pillow for screen capture.

• The Python bridge uses httpx; the CEP host uses Express; the panel UI uses React; the Claude sidecar uses the Claude Agent SDK.

License

ae-mcp project code is MIT licensed. See LICENSE.

Files carrying their own upstream license notices, such as Adobe CSInterface.js, are governed by those notices.