mcp-aftereffects

mcp-aftereffects

English | 日本語

一个 MCP 服务，可让 AI 控制 Adobe After Effects。

你可以将 Claude Code 或 Claude Desktop 等兼容 MCP 的客户端连接到正在运行的 After Effects 实例，让 AI 处理从项目检查、编辑到渲染的所有工作。

无需提供如何操作 After Effects 的详细说明。只需用自然语言说明你想要实现的效果，AI 就会检查项目状态并执行必要的操作。

Windows / macOS · After Effects 2024–2026 · Node.js 24+

注意

此工具会通过 AI 直接操作 After Effects 项目。

AI 可以读取项目内容，并修改合成、图层、效果、关键帧等。

此外，AI 从项目中读取的信息可能会发送到你正在使用的 AI 服务。这些信息可能包括合成名称、图层名称、表达式、关键帧、素材文件路径等。

如果用于受保密协议约束的项目或尚未发布的作品，请事先查看所用 AI 服务的数据保留政策以及 MCP 客户端的日志。

首次使用时，建议使用备份或测试用的 .aep 文件进行尝试，而不是使用重要项目。

功能

使用 mcp-aftereffects，你可以让 AI 执行 After Effects 任务。

• 检查项目内容
• 检查合成和图层
• 编辑图层和属性
• 添加或修改关键帧
• 编辑效果和蒙版
• 编辑文本和形状
• 设置表达式
• 保存项目
• 创建和恢复项目备份
• 渲染帧以预览更改

例如，你可以这样下达指令：

“导入这个 Illustrator 文件，并制作一些好看的文字动画。”

“应用这份 PDF 中提到的修改。”

“指出这个 AEP 中存在的问题。”

即使是复杂任务，AI 也可以在检查项目状态的同时组合所需操作。

要求

• Windows 或 macOS
• Adobe After Effects 2024 / 2025 / 2026
• Node.js 24 或更高版本
• 兼容 MCP 的客户端（Claude Code、Claude Desktop 等）

对于常规设置（一次运行一个 After Effects），无需在 After Effects 中安装插件或面板。若要同时驱动多个实例（AfterFX.exe -m），则需要一个小型启动脚本——请参阅多个 After Effects 实例。

After Effects 设置

请在 After Effects 的首选项中开启以下设置：

首选项 → 脚本和表达式 → “允许脚本写入文件并访问网络”

如果此设置处于关闭状态，AI 将无法正确执行操作。

macOS 用户

首次使用时，macOS 可能会请求允许客户端控制 After Effects。

如果未获许可，请前往：

系统设置 → 隐私与安全性 → 自动化

并允许 MCP 客户端或终端控制 After Effects。

快速开始

只要一次运行一个 After Effects，就无需在 After Effects 端进行安装。

首先，启动 After Effects 并打开要操作的项目。

接下来，将 mcp-aftereffects 注册到你的 MCP 客户端。

Claude Code

claude mcp add aftereffects -- npx -y @kumoproductions/mcp-aftereffects

Claude Desktop

将以下内容添加到 MCP 配置文件中：

{
  "mcpServers": {
    "aftereffects": {
      "command": "npx",
      "args": ["-y", "@kumoproductions/mcp-aftereffects"]
    }
  }
}

如果使用其他 MCP 客户端，请按照各自的注册方法注册 MCP 服务。

只读模式

如果你想检查或审计项目内容，而不进行任何更改，可以使用只读模式。

将以下内容添加到 MCP 客户端配置中：

{
  "mcpServers": {
    "aftereffects": {
      "command": "npx",
      "args": ["-y", "@kumoproductions/mcp-aftereffects"],
      "env": {
        "AE_MCP_READONLY": "1"
      }
    }
  }
}

你仍然可以检查项目并渲染帧以供预览。

高级设置

通常无需进行任何配置。

在某些环境中（例如 After Effects 安装在非标准位置时），可能需要进行额外设置。

指定 After Effects 位置

如果 After Effects 不在标准安装路径中，可以使用 AE_MCP_EXE 指定可执行文件的位置。

默认情况下，系统会按 2026 → 2025 → 2024 的顺序自动搜索 After Effects。

限制操作范围

使用 AE_MCP_ALLOW_CATEGORIES，可以限制 AI 可执行的操作类型。

例如，可以根据使用场景，将权限限制为仅允许执行与关键帧相关的操作。

多个 After Effects 实例

After Effects 可以同时运行多个副本（AfterFX.exe -m），每个副本都有自己的项目。默认情况下，服务只能连接到第一个通常启动的副本：通过 -m 启动的实例不会收到它所启动的脚本。要控制这些实例，请安装一次常驻代理：

npx @kumoproductions/mcp-aftereffects install-agent

这会在 After Effects 用户级别的 Scripts/Startup 文件夹中放置一个小型启动脚本（无需管理员权限；After Effects 更新后请重新运行）。从下次启动开始，每个实例（包括通过 -m 启动的实例）都会拥有自己的邮箱，服务可以选择要连接的实例：

• 服务的 env 中的 AE_MCP_INSTANCE 用于指定整个会话的默认实例，可以使用实例启动时设置的 ID，也可以使用其打开的项目文件（"shotA"、"shotA.aep"，或在两个项目同名时使用完整路径）。
• 每个工具都接受可选的 instance 参数，用于在单次调用中指定其他实例。
• ae_context 和 ae_do instance.list 会显示当前运行的实例。

要在启动时为实例命名，请在启动实例的环境中设置 AE_MCP_INSTANCE：

set AE_MCP_INSTANCE=shotA
"C:\Program Files\Adobe\Adobe After Effects 2026\Support Files\AfterFX.exe" -m

未命名的实例会获得一个随机 ID（ae-…），也可以通过其项目文件来指定。如果恰好只有一个代理正在运行，则无需任何配置；如果有多个代理正在运行且没有命名实例，调用会以 NO_INSTANCE 失败，而不会猜测要使用哪个实例。

只要 After Effects 仍在运行，代理就会持续轮询其邮箱，无论服务是否运行，因此整个会话期间，用户临时文件夹下的邮箱目录都是信任边界。安装代理时，邮箱位置会固定写入启动脚本；如果更改 AE_MCP_RUNTIME_DIR，请重新运行 install-agent（agent-status 会告知你该设置是否已过期）。

使用工作实例并行工作

AI 可以自行启动实例。instance.start 会启动一个新的 After Effects，等待其完成注册，并可打开项目的副本——这是处理主实例中已打开项目的安全方式：

1. instance.start { name: "w1", copyFrom: "<main .aep>" } — 创建一个拥有独立副本的工作实例
2. 在其中工作：使用带有 instance: "w1" 的任意工具
3. 使用 instance: "w1" 调用 ae_save_project
4. 在主实例中调用 project.merge { path: "<the copy>" } — 副本会作为文件夹导入；项目中已有的内容不会受到影响
5. instance.stop { name: "w1" }

可以同时运行多个工作实例。每个实例都是一个完整的 After Effects，因此请为每个实例预留几 GB 内存。

执行任意 ExtendScript

mcp-aftereffects 包含一项高级功能，可执行任意 ExtendScript，以处理标准操作无法完成的流程。

此功能默认处于禁用状态。

注意

启用任意 ExtendScript 后，可执行 After Effects 之外的操作。

这可能会允许执行影响整台计算机的操作，例如文件或进程操作。

此功能默认处于禁用状态。仅在必要时启用。

要启用此功能，请在 MCP 服务的环境变量中设置以下内容：

"env": {
  "AE_MCP_ENABLE_EVAL": "1"
}

仅在常规操作无法完成高级处理，或需要自定义 ExtendScript 时使用此功能。

官方发行版

说明

官方发行版仅通过 npm 和 GitHub Releases 发布。

如果从其他位置获取声称属于 @kumoproductions/mcp-aftereffects 的软件包，或声称是此服务的文件，请务必谨慎。

故障排除

操作超时

请检查以下事项：

• After Effects 是否正在运行？
• 是否已打开项目？
• “允许脚本写入文件并访问网络”是否已开启？
• 在 macOS 上，是否已启用自动化权限？

NO_INSTANCE

调用时没有可供连接的 After Effects。可能是所有正在运行的 After Effects 都通过 -m 启动，且未安装 Agent（请参阅多个 After Effects 实例）；AE_MCP_INSTANCE / instance 指定的实例未运行或卡在对话框中；或者有多个 Agent 正在运行，但未指定其中任何一个。错误信息会列出当前运行的实例。

DIALOG_OPEN — After Effects 正在显示对话框

当 After Effects 显示模态对话框时，任何脚本都无法运行，无论是驻留 Agent 还是通过 -r 启动的脚本。最常见的原因是打开了素材或字体缺失的项目（“自上次保存此项目后，已有 N 个文件丢失”）；该对话框通常隐藏在主窗口后面。错误信息会引用对话框文本（macOS 上的情况请见下文）。

• instance.dialogs 会列出所有正在运行的 After Effects 当前显示的对话框。
• instance.dismiss_dialog { id } 会按 Escape 关闭对话框，即执行对话框的取消操作：警告会被确认，而“关闭前是否保存更改？”之类的问题会被取消，而非作答，因此不会保存或丢弃任何内容。如果你想以不同方式作答，必须亲自点击对话框。
• 对话框消失后，Agent 会自动恢复运行；无需重启。
• 若要避免出现文件缺失警告，请在不打开项目的情况下启动 After Effects，然后使用 project.open 打开项目，这样就不会弹出该对话框。

Windows 和 macOS 均支持对话框检测。macOS 上有两种检测方式：

• 如果为运行 MCP 服务的应用授予了辅助功能权限（“系统设置” > “隐私与安全性” > “辅助功能”——你的终端或 MCP 客户端应用），系统就能找到所有对话框并读取其文本；instance.dismiss_dialog 的工作方式与 Windows 相同：按 Escape 执行取消操作。“关闭前是否保存更改？”提示会被取消（项目保持打开且未保存）；警告或脚本 alert() 会被确认。After Effects 不会被置于最前方。
• 如果未授予该权限，系统只能根据窗口列表推测对话框：大多数对话框都能被找到，但文本为空（accessibility: false）；有些对话框（例如 Adobe 许可提示）则无法检测到，并且无法通过此方式关闭任何对话框。

已在 After Effects 26.5 / macOS 26.4 上验证，测试内容包括文件缺失警告、脚本 alert()、保存提示和系统兼容性报告。

After Effects 停在“我们检测到崩溃”对话框

如果 After Effects 进程被终止（通过任务管理器、taskkill 或崩溃），下次启动时会显示安全模式对话框并等待点击——包括通过 instance.start 启动的实例，这些实例随后会因 did not register 而失败。请在屏幕上关闭该对话框。正常退出的实例不会触发此对话框，因此请优先使用 instance.stop，而不是强行终止进程。

找不到 After Effects

如果你将 After Effects 安装在非标准位置，请设置 AE_MCP_EXE。

如果问题仍然存在，请通过 Issue 报告，或联系 @cumuloworks。

开发者信息

有关内部 MCP 工具、与 After Effects 的通信方式、ExtendScript、测试环境以及如何添加自定义操作的信息，请参阅开发者文档。

• docs/TOOLS.md
• CONTRIBUTING.md

贡献

欢迎提交 Bug 报告、功能请求和 Pull Request。

有关如何设置开发环境和内部架构的信息，请参阅 CONTRIBUTING.md。

许可证

MIT © 2026 kumo.productions, Inc.

商标

Adobe® 和 Adobe After Effects® 是 Adobe Inc. 的商标。

本项目是一款独立的非官方工具，与 Adobe 无关联，也未获得 Adobe 的认可。