ae-mcp

ae-mcp

English | 简体中文

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.

让 AI 读取你的 After Effects 项目、构建动画、检查结果，并将成功的操作保存为可重复使用的工具。

ae-mcp 是一个开源 CEP 扩展，可将正在运行的 After Effects 项目连接到 Model Context Protocol（MCP）。你可以在面板中与 Claude、Codex 或 OpenCode 对话，也可以连接外部 MCP 客户端来处理合成、图层、关键帧和表达式。

下载 v0.11.1 · 安装 · 工具参考 · 更新日志

功能

• 读取真实项目状态： 通过分页、排序和筛选检查项目、合成、图层、属性和关键帧。
• 构建和编辑动画： 使用 ExtendScript 执行常规 AE 操作；使用原生 AEGP 工具获取精确的时间和对象定位信息。
• 检查合成像素： 从 AE 导出 PNG 帧，以网格方式对多个时间点进行采样，并比较 A/B 像素差异。
• 恢复失败的操作： 使用已保存项目的检查点、捕获的失败脚本和 recoveryId 来检查、修正或恢复状态。
• 保留可重复使用的工具： 成功的脚本会成为可重放的候选项，可保存、固定、归档、导出和导入；同时也支持提示词技能。
• 跟进执行过程： 使用面板中的审批、活动时间线、对话历史和诊断导出功能。

工作流为：读取 → 执行 → 预览 → 修正 → 保存以供重复使用。AI 通过 AE 主机读取当前状态，包括尚未保存的更改，并通过项目结构和合成预览检查 结果。

完整工作流

在测试项目中尝试这样的任务：

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.

截图展示了任务输入、六帧预览，以及捕获到工具库中的成功脚本。这些是展示 工作流的实际 v0.10.7 界面；v0.11.0 新增内容见下文。

描述任务	检查结果	保留可重复使用的工具

v0.11.1 新增内容

• 修复原生 Codex 图像预览、缩放和对话历史问题。
• 改进外部 MCP 使用指南、工具库扫描，以及 Windows AE 进程发现和重试功能。
• Windows 和 macOS 原生插件仍为 0.11.0；现有用户只需手动更新 ZXP。

v0.11.0 新增内容

• **多个实例和并行预览：**外部客户端可以发现、启动多个 AE 实例并将请求路由到这些实例。不同项目可以并行运行；每个项目有一个活动写入者，而只读工作线程可以检查固定检查点快照并进行预览。
• **会话移交：**面板对话轮次或外部 AE 调用结束后，其他符合条件的会话可以接手空闲项目。正在进行的调用、引擎排空过程以及结果不确定的写入仍会阻止移交。
• **AI 工作目录：**新对话默认使用当前 AEP 所在的文件夹；如果项目尚未保存或目录不可写，则改用用户主目录。可在 Settings 中选择文件夹或恢复默认设置；现有对话会保留原目录。
• **撤销和恢复修复：**修复了撤销组不匹配和检查点恢复上下文的问题。渲染必须单独运行，不能在撤销组内执行。
• **原生组件和工作线程可靠性：**改进了冷启动时的原生组件诊断、连接超时恢复，以及 Windows 后台工作线程的启动和关闭清理。
• **16 个公开工具，较之前的 13 个有所增加：**新增 ae_instances、ae_workspace 和 ae_readJob，并提供匹配的 [email protected] stdio 连接器。

此版本提供适用于 Windows/macOS 的通用 ZXP、适用于 Windows x64 和 macOS arm64 的原生插件，以及校验和。最终版 Mac 包已在 AE 26.3x87 arm64 上完成限定范围内的读写、撤销、渲染、恢复和安装检查。Mac 工作线程场景尚未验证。有关验证范围和已知限制，请参阅 v0.11.0 发布说明。

安装和首次运行

1. 从 v0.11.1 发布页面 下载并安装 ae-mcp-panel-v0.11.1.zxp。
2. 使用 ae_nativeExec 时，请从同一发布页面下载原生插件： Windows x64 对应 AeMcpNative-v0.11.0-windows-x64.aex，macOS arm64 对应 AeMcpNative-v0.11.0-macos-arm64.plugin.zip。解压 Mac ZIP 并安装 AeMcpNative.plugin。原生插件与 ZXP 分开提供；有关安装位置和 macOS 下载隔离处理，请参阅 Install。 Mac 包要求 macOS 14.0 或更高版本。 两个平台使用相同的约 60 MB ZXP，其中包含 Windows OpenCode 运行时；macOS 则使用 PATH 中的 OpenCode。
3. 启动 After Effects 并打开 Window > Extensions > ae-mcp。外部客户端使用 MCP 期间，请保持面板打开。
4. 在面板的 Settings 中配置 Claude、Codex 或 OpenCode，或按下文所述连接外部客户端。

面板本身就是 MCP 服务，无需单独的仓库服务端。 外部客户端必须与 After Effects 在同一台计算机上运行，因为默认端点使用回环地址。

客户端连接

对于正在运行的面板，支持 Streamable HTTP 的客户端可以连接到面板中显示的 URL。例如，使用默认地址的 Claude Code：

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

若要发现并启动实例，或使用 Claude Desktop 等 stdio 客户端， 请使用对应的连接器（需要 Node.js 18 或更高版本）：

{
  "mcpServers": {
    "ae": {
      "command": "npx",
      "args": ["-y", "[email protected]"]
    }
  }
}

如果未显式指定 URL，连接器会发现已安装扩展的多实例入口。它不会安装或更新扩展。使用 ae_instances 发现或显式启动实例，使用 ae_workspace 绑定项目，并在后续 AE 调用中 传入返回的 context_id。设置 --url 或 AE_MCP_HTTP_URL 会将转发固定到一个端点。关闭面板属于主动断开连接，不会自动重新打开 AE。

或者，运行已随安装扩展提供的无依赖 stdio 垫片。此示例会将连接固定到一个端点。将 command 设置为系统 Node，并将 args 指向扩展目录中的 host/stdio-shim.js：

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

完成设置后刷新或重新连接客户端，然后调用 ae_status 进行验证。

工作原理

MCP 服务直接运行在 CEP 面板的 Node 主机中，默认地址为 http://127.0.0.1:11488/mcp。其他实例会注册各自的端点。主机负责管理审批、项目上下文、工具库 和日志。

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 处理常规操作。原生 AEGP 平面保留了 23 个固定原语，用于精确的有理数时间和绑定到代次的对象定位符。多个实例并不意味着可以同时写入同一个项目； 工作线程结果始终描述其指定的检查点快照。详情请参阅架构。

面板功能

CEP 主机提供 16 个公开 MCP 工具：

成功执行的 ae_exec 和 ae_execRecover 脚本会被捕获为去重且可重新运行的工具库候选项。ae_toolSave 可创建或提升可复用的 JSX 和提示词技能工件；“工具”页面可管理候选项和已保存的 工件，包括导入和导出。使用计数器和漏斗事件会显示哪些内容被重放或保留，而占位符防护器会将经过压缩的 对话指向确切的候选项，并阻止重复的占位符重试。

面板还提供审批模式、活动历史记录、诊断、日志导出，以及内置的 Claude、Codex 和 OpenCode 渠道。持久化主机状态默认存储在 ~/.ae-mcp；开发者和测试可以使用 AE_MCP_STATE_DIR 将其迁移到其他位置。

公开的 MCP 工具由 CEP 主机提供。写入操作后应进行独立回读；可能产生副作用的失败必须先 核对处理，然后才能重试；撤销操作必须单独执行并验证。超时无法保证同步 ExtendScript 立即中断； PNG 预览可能不包含 Guide 图层。有关多帧和差异参数、恢复规则及快照任务，请参阅参考文档。

开发

安装两个 Node 工作区并构建面板：

(cd plugin/host && npm ci)
(cd plugin/panel && npm ci && npm run build)

对于本地 CEP 部署，请在宿主和面板构建完成后使用平台专用脚本：

.\scripts\install-plugin-dev.ps1

./scripts/install-plugin-dev-macos.sh

Adobe After Effects C/C++ Plug-in SDK 由开发者提供，且必须保留在此仓库之外。构建本机插件前，请先验证该 SDK：

node scripts/package/ae-sdk-input.mjs verify-input --platform macos-arm64

对于已冻结的本机平面，请在仓库外的新目录中进行构建。安装程序会将事务状态保存在 native-plugin-dev-v1 下；如果要安装构建结果，请保留返回的事务 ID：

AE_SDK_ARCHIVE=/absolute/path/AfterEffectsSDK.zip
AE_SDK_ROOT=/absolute/path/AfterEffectsSDK
BUILD_DIR=/private/tmp/ae-mcp-native-dev
TRANSACTION_ID="paste-the-transaction-id-here"
node native/ae-plugin/build-macos.mjs \
  --sdk-archive "$AE_SDK_ARCHIVE" \
  --sdk-root "$AE_SDK_ROOT" \
  --output "$BUILD_DIR"
# The install state root is native-plugin-dev-v1.
node native/ae-plugin/install-dev-macos.mjs install --artifact-dir "$BUILD_DIR"
node native/ae-plugin/install-dev-macos.mjs rollback \
  --transaction "$TRANSACTION_ID"

本机平面已冻结；生成的 AEGP 协议文件已纳入版本控制，能力包代码生成流水线不属于常规开发内容。

测试和打包

在本地运行有针对性的 Node 契约测试：

node --test scripts/package/test/verify-windows-zxp-stage.test.mjs
node --test scripts/package/test/zxp-payload-audit.test.mjs

Windows ZXP 暂存命令会复制面板、宿主、JSX、共享模块、图标、生成的宿主资源，以及由 node scripts/package/fetch-opencode-runtime.mjs 暂存的固定版本 OpenCode 运行时。该命令会验证宿主对 Express 4.22.2 的精确依赖，并对 ZXP 签名一次：

.\scripts\package-zxp.ps1 -SkipSigning

签名后的 ZXP 中不得包含嵌套的本机二进制文件；捆绑的 opencode.exe 是唯一明确允许的可执行文件。打包脚本会在文件超过 80 MB 时失败；包含运行时的发布包约为 60 MB。

维护中的操作和开发详情，请参阅 安装、参考、工具库、架构、工作流和发布。

赞助者

感谢所有支持 ae-mcp 开发和维护的人！

赞助完全自愿，任何金额都值得感谢。您的支持有助于项目的开发和维护。

通过 PayPal 支持

扫码通过微信支付或支付宝支持

请使用相应的应用扫码。

微信支付	支付宝

赞助者鸣谢

许可证

ae-mcp 根据 MIT License 发布；请参阅 LICENSE。Adobe 的 CSInterface.js 保留其上游许可证声明。