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.

The current release line is v0.9.0.

Architecture

Embedded panel chat or external MCP client
  -> packages/core (ae_mcp, Python stdio MCP server, 32 ae_ tools)
  -> backend (packages/bridge, httpx)
  -> CEP panel Node host (plugin/host, Express, 127.0.0.1:11488)
  -> CSInterface.evalScript
  -> ExtendScript (plugin/jsx/runtime.jsx + jsx_templates/*.jsx)
  -> After Effects

ae_previewFrame renders real comp pixels through CompItem.saveFrameToPng, with viewer snapshot only as a fallback. packages/snapshot-mss provides the cross-platform mss screenshot backend for ae_snapshot screen capture.

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 panel layer handles backend setup, approvals, diagnostics, activity history, and first-run dependency installation. Claude, Codex, and ZCode are built-in panel backends; OpenCode and other tools can still connect as external MCP clients.

Related MCP server: After Effects MCP Server

v0.9.0 Update

• Added a unified Provider Manager for custom model providers instead of scattering provider setup across backend-specific settings.

• Provider Manager can add, edit, delete, and probe OpenAI-compatible and Anthropic providers. Provider config is stored locally at ~/.ae-mcp/providers.json.

• Redesigned Settings around backend credential channels and editable provider records. Editable items can expand for details and collapse back into compact status rows, keeping the settings page easier to scan.

• Claude API direct, Codex OpenAI-compatible providers, and ZCode provider configuration now share the same provider-management model where applicable. Legacy Claude BYOK preferences migrate automatically.

• OpenCode remains an external MCP client. Embedded OpenCode is implemented but not exposed yet, pending approval-gating verification.

Install and First Run

For normal users, install the panel first and let the first-run wizard install the local dependencies.

1. Install the ZXP package with aescripts ZXP Installer or ExMan Cmd.

2. Restart After Effects after installing the ZXP.

3. Open Window -> Extensions -> ae-mcp.

4. Follow the first-run wizard.

The wizard detects and installs the required local tools: uv, Node, Claude CLI, and ae-mcp. Every install command is shown verbatim before it runs. Login actions open a visible terminal window. After the wizard installs Python-side dependencies, AE does not need another restart.

ae-mcp is not on PyPI. Do not use the public PyPI name as the install source.

If you need the Python packages directly from a release tag:

uv tool install --from git+https://github.com/JUNKDOGE-JOE/after-effects-mcp@v0.9.0#subdirectory=packages/core ae-mcp --with git+https://github.com/JUNKDOGE-JOE/after-effects-mcp@v0.9.0#subdirectory=packages/bridge --with git+https://github.com/JUNKDOGE-JOE/after-effects-mcp@v0.9.0#subdirectory=packages/snapshot-mss

For a development checkout:

uv tool install --from packages/core ae-mcp --with packages/bridge --with packages/snapshot-mss

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.

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

• Activity stream for agent operations.

• Kill switch to stop all AI operations immediately.

• Diagnostics for host status, access token, Python client signal, AE project state, ExtendScript ping, and local uv / node / claude availability.

• 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

Use the panel-generated MCP config for external clients. A minimal config looks like this:

{
  "mcpServers": {
    "ae": {
      "command": "ae-mcp",
      "env": {
        "AE_MCP_BACKEND": "ae-mcp",
        "AE_MCP_PLUGIN_URL": "http://127.0.0.1:11488"
      }
    }
  }
}

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

Expression workflows should run ae_validateExpressions before visual review. For risky edits, use ae_checkpoint or pass checkpoint_label to ae_exec.

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

Repository 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

The macOS development script exists, but v0.9.0 validation is primarily Windows + AE live.

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

Packaging a release ZXP requires Adobe ZXPSignCmd and a certificate password:

.\scripts\package-zxp.ps1 -ZxpSignCmd C:\Tools\ZXPSignCmd.exe -CertPassword <pw>

The script stages plugin/, strips development debug files and panel source, installs host/sidecar production dependencies, signs the package, and writes release/ae-mcp-panel.zxp. See docs/RELEASE.md for the full release checklist.

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.