Skip to content
Back to search

mcp-aftereffects

TypeScript MCP server for Adobe After Effects (Windows & macOS) — project/comp/layer introspection, atomic undo-grouped operations, JSON project export/import, and single-frame rendering via file IPC.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/kumoproductions--mcp-aftereffects/badge.svg)](/listings/kumoproductions--mcp-aftereffects)

HTML

<a href="/listings/kumoproductions--mcp-aftereffects"><img src="/api/listings/kumoproductions--mcp-aftereffects/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

No installation is required on the After Effects side as long as you run one After Effects at a time.

First, launch After Effects and open the project you wish to operate on.

Next, register mcp-aftereffects with your MCP client.

Claude Code

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

Claude Desktop

Add the following to your MCP configuration file:

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

If you are using other MCP clients, please follow their respective registration methods for MCP servers.

Read-Only Mode

If you want to inspect or audit project content without making any changes, you can use read-only mode.

Add the following to your MCP client configuration:

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

You can still investigate the project and render frames for preview.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 284 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ![MCP for After Effects](https://raw.githubusercontent.com/kumoproductions/mcp-aftereffects/main/assets/ogp.png)
  2. # mcp-aftereffects
  3. [![CI](https://github.com/kumoproductions/mcp-aftereffects/actions/workflows/ci.yml/badge.svg)](https://github.com/kumoproductions/mcp-aftereffects/actions/workflows/ci.yml)
  4. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
  5. [![Node](https://img.shields.io/badge/node-%3E%3D24-informational)](package.json)
  6. [![After Effects](https://img.shields.io/badge/After%20Effects-2024%E2%80%932026-informational)](https://www.adobe.com/products/aftereffects.html)
  7. [![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS-informational)](#requirements)
  8. English | [日本語](./README.ja.md)
  9. An MCP server that enables AI to control Adobe After Effects.
  10. You can connect MCP-compatible clients such as Claude Code or Claude Desktop to a running instance of After Effects, allowing the AI to handle everything from project inspection and editing to rendering.
  11. There is no need to provide detailed instructions on how to operate After Effects. Simply explain what you want to achieve in natural language, and the AI will check the project status and perform the necessary operations.
  12. **Windows / macOS · After Effects 2024–2026 · Node.js 24+**
  13. > [!CAUTION]
  14. > **This tool directly manipulates After Effects projects via AI.**
  15. >
  16. > The AI can read project contents and modify compositions, layers, effects, keyframes, and more.
  17. >
  18. > Additionally, information the AI reads from the project may be sent to the AI service you are using. This may include composition names, layer names, expressions, keyframes, footage file paths, etc.
  19. >
  20. > If using this for projects under NDA or unreleased works, please check the data retention policy of the AI service you are using and the logs of your MCP client beforehand.
  21. >
  22. > For first-time use, we recommend trying it with a backup or a test .aep file rather than a critical project.
  23. ## Capabilities
  24. With mcp-aftereffects, you can request the AI to perform After Effects tasks.
  25. - Inspect project contents
  26. - Investigate compositions and layers
  27. - Edit layers and properties
  28. - Add or modify keyframes
  29. - Edit effects and masks
  30. - Edit text and shapes
  31. - Set expressions
  32. - Save projects
  33. - Create and restore project backups
  34. - Render frames to preview changes
  35. For example, you can give instructions like these:
  36. > "Import this Illustrator file and create some nice-looking text motion."
  37. > "Apply the revisions mentioned in this PDF."
  38. > "Point out any issues in this AEP."
  39. Even for complex tasks, the AI can combine necessary operations while checking the project status.
  40. ## Requirements
  41. - Windows or macOS
  42. - Adobe After Effects 2024 / 2025 / 2026
  43. - Node.js 24 or higher
  44. - MCP-compatible client (Claude Code, Claude Desktop, etc.)
  45. No plugins or panels need to be installed within After Effects for the usual setup: one After Effects at a time. Driving several instances at once (`AfterFX.exe -m`) is the one case that needs a small startup script — see [Multiple After Effects Instances](#multiple-after-effects-instances).
  46. ### After Effects Settings
  47. In After Effects Preferences, please turn ON the following:
  48. **Preferences → Scripting & Expressions → "Allow Scripts to Write Files and Access Network"**
  49. If this setting is OFF, the AI will not be able to perform operations correctly.
  50. ### For macOS
  51. Upon first use, macOS may request permission for the client to control After Effects.
  52. If it is not permitted, go to:
  53. **System Settings → Privacy & Security → Automation**
  54. and allow your MCP client or terminal to control After Effects.
  55. ## Quick Start
  56. No installation is required on the After Effects side as long as you run one After Effects at a time.
  57. First, launch After Effects and open the project you wish to operate on.
  58. Next, register mcp-aftereffects with your MCP client.
  59. ### Claude Code
  60. ```bash
  61. claude mcp add aftereffects -- npx -y @kumoproductions/mcp-aftereffects
  62. ```
  63. ### Claude Desktop
  64. Add the following to your MCP configuration file:
  65. ```json
  66. {
  67. "mcpServers": {
  68. "aftereffects": {
  69. "command": "npx",
  70. "args": ["-y", "@kumoproductions/mcp-aftereffects"]
  71. }
  72. }
  73. }
  74. ```
  75. If you are using other MCP clients, please follow their respective registration methods for MCP servers.
  76. ### Read-Only Mode
  77. If you want to inspect or audit project content without making any changes, you can use read-only mode.
  78. Add the following to your MCP client configuration:
  79. ```json
  80. {
  81. "mcpServers": {
  82. "aftereffects": {
  83. "command": "npx",
  84. "args": ["-y", "@kumoproductions/mcp-aftereffects"],
  85. "env": {
  86. "AE_MCP_READONLY": "1"
  87. }
  88. }
  89. }
  90. }
  91. ```
  92. You can still investigate the project and render frames for preview.
  93. ## Advanced Settings
  94. Usually, no configuration is necessary.
  95. In some environments, such as when After Effects is installed in a non-standard location, additional settings may be required.
  96. ### Specifying After Effects Location
  97. If After Effects is not in the standard installation path, you can specify the executable location using `AE_MCP_EXE`.
  98. By default, it automatically searches for After Effects in the order of 2026 → 2025 → 2024.
  99. ### Limiting Operation Scope
  100. Using `AE_MCP_ALLOW_CATEGORIES`, you can restrict the types of operations permitted for the AI.
  101. For example, you can limit permissions to only keyframe-related operations depending on your use case.
  102. ### Multiple After Effects Instances
  103. After Effects can run several copies at once (`AfterFX.exe -m`), each with its own project. Out of the box the server reaches only the first, normally started copy: instances started with `-m` never receive the scripts it launches. To drive them, install the resident agent once:
  104. ```bash
  105. npx @kumoproductions/mcp-aftereffects install-agent
  106. ```
  107. This drops a small startup script into After Effects' user-level `Scripts/Startup` folder (no admin rights needed; run it again after an After Effects update). From the next launch on, every instance — including `-m` ones — serves a mailbox of its own, and the server picks which instance to talk to:
  108. - `AE_MCP_INSTANCE` in the server's `env` names the default instance for the whole session, either by the id the instance was started with or by the project file it has open (`"shotA"`, `"shotA.aep"`, or a full path when two projects share a name).
  109. - Every tool takes an optional `instance` argument to address another instance for a single call.
  110. - `ae_context` and `ae_do instance.list` show what is live.
  111. To name an instance at launch, set `AE_MCP_INSTANCE` in the environment that starts it:
  112. ```bat
  113. set AE_MCP_INSTANCE=shotA
  114. "C:\Program Files\Adobe\Adobe After Effects 2026\Support Files\AfterFX.exe" -m
  115. ```
  116. An unnamed instance gets a random id (`ae-…`) and can still be addressed by its project file. With exactly one live agent no configuration is needed at all; with several live and none named, calls fail with `NO_INSTANCE` instead of guessing.
  117. The agent keeps polling its mailbox for as long as After Effects runs, server or no server, so the mailbox directory under your per-user temp folder stays the trust boundary for the whole session. The mailbox location is fixed into the startup script when you install it; if you change `AE_MCP_RUNTIME_DIR`, run `install-agent` again (`agent-status` tells you when it is out of date).
  118. ### Parallel Work with Worker Instances
  119. The AI can start instances itself. `instance.start` launches a new After Effects, waits for it to register, and can open a **copy** of a project — the safe way to work on something the main instance has open:
  120. 1. `instance.start { name: "w1", copyFrom: "<main .aep>" }` — a worker with its own copy
  121. 2. Work in it: any tool with `instance: "w1"`
  122. 3. `ae_save_project` with `instance: "w1"`
  123. 4. `project.merge { path: "<the copy>" }` in the main instance — the copy comes in as a folder; nothing already in the project is touched
  124. 5. `instance.stop { name: "w1" }`
  125. Several workers can run at once. Each is a full After Effects, so plan on a few gigabytes of memory per instance.
  126. ## Execution of Arbitrary ExtendScript
  127. mcp-aftereffects includes an advanced feature to execute arbitrary ExtendScript for processes that cannot be handled by standard operations.
  128. This feature is **disabled by default**.
  129. > [!CAUTION]
  130. > **Enabling arbitrary ExtendScript allows operations outside of After Effects.**
  131. >
  132. > **This may permit actions that affect your entire computer**, such as file or process manipulation.
  133. >
  134. > This feature is disabled by default. Enable it only if necessary.
  135. To enable it, set the following in your MCP server environment variables:
  136. ```json
  137. "env": {
  138. "AE_MCP_ENABLE_EVAL": "1"
  139. }
  140. ```
  141. Use this feature only for advanced processing that cannot be achieved through regular operations or when custom ExtendScript is required.
  142. ## Official Releases
  143. > [!NOTE]
  144. > **Official releases are distributed only through npm and GitHub Releases.**
  145. >
  146. > Please exercise caution if obtaining packages claiming to be `@kumoproductions/mcp-aftereffects` or files claiming to be this server from any other location.
  147. ## Troubleshooting
  148. ### Operations Timeout
  149. Please check the following:
  150. - Is After Effects running?
  151. - Is a project open?
  152. - Is "Allow Scripts to Write Files and Access Network" turned ON?
  153. - On macOS, is the Automation permission enabled?
  154. ### `NO_INSTANCE`
  155. The call had no After Effects to go to. Either every running After Effects was started with `-m` and the agent is not installed (see [Multiple After Effects Instances](#multiple-after-effects-instances)), the instance named by `AE_MCP_INSTANCE` / `instance` is not running or is stuck in a dialog, or several agents are live and none was named. The error lists what is live.
  156. ### `DIALOG_OPEN` — After Effects Is Showing a Dialog
  157. While After Effects shows a modal dialog, no script runs at all — neither the resident agent nor a `-r` launch. The most common cause is opening a project whose footage or fonts are missing ("N files are missing since you last saved this project"), and the dialog is often hidden behind the main window. The error quotes the dialog's text (on macOS, see below).
  158. - `instance.dialogs` lists the dialogs every running After Effects is showing.
  159. - `instance.dismiss_dialog { id }` closes it with Escape, the dialog's cancel action: a warning is acknowledged, and a question such as "Save changes before closing?" is cancelled rather than answered — nothing is saved or discarded. A dialog you want answered differently has to be clicked by you.
  160. - The agent resumes on its own once the dialog is gone; no restart is needed.
  161. - To avoid the missing-files warning in the first place, start After Effects without a project and open it with `project.open`, which suppresses the dialog.
  162. Dialog detection works on Windows and macOS. On macOS it has two tiers:
  163. - With Accessibility permission for the app that runs the MCP server (System Settings > Privacy & Security > Accessibility — your terminal, or the MCP client app), every dialog is found and its text read, and `instance.dismiss_dialog` works the same way as on Windows: Escape, the cancel action. A "Save changes before closing?" prompt is cancelled (the project stays open and unsaved); a warning or script `alert()` is acknowledged. After Effects is not brought to the front.
  164. - Without that permission, dialogs are only guessed at from the window list: most are found, with empty text (`accessibility: false`), but some — such as the Adobe licensing prompt — are missed, and none can be dismissed from here.
  165. Verified on After Effects 26.5 / macOS 26.4 with the missing-files warning, a script `alert()`, the save prompt and the System Compatibility Report.
  166. ### After Effects Stops at a "We detected a crash" Dialog
  167. If an After Effects process was killed (Task Manager, `taskkill`, a crash), the next launch shows the Safe Mode dialog and waits for a click — including instances started by `instance.start`, which then fail with `did not register`. Dismiss the dialog on screen. An instance that quits normally does not trigger it, so prefer `instance.stop` over killing.
  168. ### After Effects Not Found
  169. If you have installed After Effects in a non-standard location, please set `AE_MCP_EXE`.
  170. If the issue persists, please report it via an Issue or to @cumuloworks.
  171. ## Developer Information
  172. For information regarding internal MCP tools, communication methods with After Effects, ExtendScript, test environments, and how to add custom operations, please refer to the developer documentation.
  173. - `docs/TOOLS.md`
  174. - `CONTRIBUTING.md`
  175. ## Contributing
  176. Bug reports, feature requests, and Pull Requests are welcome.
  177. For information on setting up the development environment and the internal architecture, please refer to `CONTRIBUTING.md`.
  178. ## License
  179. MIT © 2026 kumo.productions, Inc.
  180. ## Trademark
  181. Adobe® and Adobe After Effects® are trademarks of Adobe Inc.
  182. This project is an independent, unofficial tool and is **not affiliated with or endorsed by Adobe**.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.