Cavi After Effects MCP
MCP server for headless Adobe After Effects on macOS. It starts After Effects without its UI, runs
ExtendScript with arguments and returns the script's JSON report, and renders saved projects with aerender,
checking every output movie's frame count. 45 tools cover comps, layers, shapes, masks, text, keyframes,
effects, 3D, transitions, templates, Essential Graphics and delivery.
Try one title
Put a lower third over a shot: the footage pushes in, a name bar slides in, and two lines of text rise in. The frame below was rendered by headless After Effects from that comp at 2.5 seconds.
The calls are in run.py and the shot is in examples/first-result/media. The comp is 1280 by 720, 3.5 seconds at 24 fps, with five layers. Reproduce the title with one command; the calls are explained in Your first comp.
Install
Requires macOS, After Effects 2026 or later, FFmpeg (ffmpeg and ffprobe on PATH) and Python 3.15 or
later with uv. You supply your own licensed Adobe applications.
uv tool install cavi-after-effects-mcp
Upgrade with uv tool upgrade cavi-after-effects-mcp. To work from a checkout instead, see
CONTRIBUTING.md.
Quickstart
Register the stdio server with your MCP client:
{"mcpServers": {"after-effects": {"command": "cavi-after-effects-mcp"}}}
If your client does not inherit your shell's PATH, use the absolute path that
command -v cavi-after-effects-mcp prints. Then ask your agent to:
- Call
ae_status. It reports the After Effects it found and its version, or the reason it found none. - Call
ae_launch. It starts one headless instance and waits until it answers. - Create a comp with
ae_comp_new, passing an absolute path forproject. The project is created and saved. - Add layers, animation and effects, then look with
ae_frameor write a movie withae_export_frames. - Render a queue with
ae_render_queue_setandae_render_queue.
Every tool that edits a project takes the project's absolute path and saves it. After Effects runs with no UI, so nothing is open on screen; a call that fails leaves the project as it was.
What it does
| Area | Tools |
|---|---|
| Session | ae_status, ae_launch, ae_script |
| Project | ae_inspect, ae_project, ae_project_settings, ae_import, ae_footage_replace, ae_collect, ae_organize, ae_fonts, ae_effects, ae_presets |
| Comps and layers | ae_comp_new, ae_comp_set, ae_layer_add, ae_layer_set, ae_layer_edit, ae_text_set, ae_shape_add, ae_mask, ae_camera, ae_material, ae_markers |
| Animation | ae_keyframes, ae_expressions, ae_effect_add, ae_preset_apply, ae_text_animator, ae_controls, ae_audio, ae_time, ae_properties |
| Transitions | ae_transitions, ae_transition, ae_sequence_layers |
| Delivery | ae_render_queue_set, ae_render_queue, after_effects_render, ae_frame, ae_export_frames, ae_template_render, ae_essential_graphics, ae_essential_override, ae_mogrt_export |
Each tool carries its access in its annotations: read-only, write, or destructive. The
tool reference lists every tool's parameters and
result fields, and a test fails when it and the server's registry differ. Three calls always refuse, because
headless After Effects aborts on the underlying operation, and name the supported alternative instead:
ae_preset_apply, ae_mogrt_export and convert_to_keyframes of ae_audio. See
Measured behavior.
Script contract
ae_script(script, project, args) defines the global CAVI_ARGS (the args object), then runs the script. The
script sets its report with caviReport(object), which stores the JSON in the saved project. A script that
never calls caviReport reports {"value": <its last value>}. A report with a non-empty errors list fails
the call with those errors. Before running, the runner compiles the script inside try, so a syntax error
comes back as a message with its line. A script that fails leaves no partial edits.
var comp = app.project.items.addComp("Title", 1920, 1080, 1, 2, 30);
caviReport({comp: comp.name, frames: 60, errors: []});
ae_script refuses scripts that call applyPreset, executeCommand or findMenuCommandId, which abort
headless After Effects.
Rendering
ae_render_queue runs aerender on a saved project's queue and checks each declared output's frame count with
ffprobe. A movie that is missing, older than the render or short of frames is rendered again on its own. If
that still fails, the movie is encoded from saveFrameToPng frames with ffmpeg and the output reports which
path produced it. ae_export_frames writes a frame range without aerender at all. See
Rendering and the fallback.
after_effects_render renders one declared composition range of a workspace project to a new PNG directory
and writes a receipt. The recipe:
{
"version": 1, "name": "Title", "project": "titles/title.aep",
"dependencies": ["titles/aisle.mp4"], "composition": "Title", "start": 0, "end": 83,
"fps": {"numerator": 24, "denominator": 1}, "loop": false, "alpha": "straight",
"output_module": "RGBA PNG"
}
Start and end are inclusive frames. The output module must be an existing straight-alpha RGBA PNG template,
and exactly one aerender must be installed.
Documentation
The documentation source is in docs/after-effects-mcp/source:
- Overview and setup
- Guides: your first comp, templates and Essential Graphics, rendering and the fallback and troubleshooting
- Reference: tools, configuration, measured behavior and testing and evaluation
- Security model and version and support
Configuration
| Variable | Meaning |
|---|---|
CAVI_AFTER_EFFECTS_APP |
Absolute path of the After Effects .app to use. A wrong path is reported, never replaced by another install. Default: the newest Adobe After Effects 20* in /Applications. |
CAVI_ADOBE_WORKSPACE |
Workspace folder for after_effects_render; its recipe and output must stay inside it. |
CAVI_ADOBE_DATA |
Private state directory of the shared Adobe package. |
Security
The server speaks MCP over stdio, sends no telemetry and uses no accounts. It runs ExtendScript with the
permissions of the user who started it. Only after_effects_render is confined to a workspace folder; the
other tools take any absolute path and can write there, and ae_script runs arbitrary ExtendScript. Run it
only for clients you trust. See the security model and
SECURITY.md.
Tests
uv sync --locked --dev
uv run --locked ruff check .
uv run --locked pytest -q
uv run --locked python evals/run.py
The unit tests and the evaluations drive the registered tools through the server and never start After
Effects; tests that need FFmpeg skip without it. A test fails when the tool reference and the registry differ,
when the documentation build is not reproducible, or when a link in the README or the pages is broken. The
evaluations play each case in evals/cases.json against the server over stdio. See
Testing and evaluation.
Contributing
See CONTRIBUTING.md for setup, checks and the rules for changes. This project follows the Code of Conduct.
License
MIT. See LICENSE.
Trademarks
Adobe and After Effects are either registered trademarks or trademarks of Adobe in the United States and/or other countries. This project is not affiliated with, endorsed by, or sponsored by Adobe. It does not include or redistribute Adobe software, templates or presets; you supply your own licensed applications.
Metadata
Release files for cavi-after-effects-mcp 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| cavi_after_effects_mcp-0.1.0.tar.gz | 90.1 kB | With provenance | Details for cavi_after_effects_mcp-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| cavi_after_effects_mcp-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for cavi_after_effects_mcp-0.1.0-py3-none-any.whl |
Total release size: 175.2 kB
Release files / cavi_after_effects_mcp-0.1.0.tar.gz
| Download URL | cavi_after_effects_mcp-0.1.0.tar.gz |
|---|---|
| Size | 90.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e9880008a1ac3c3a0e819f75a7b365d54cb235824b3af798abe794277b8a85f2
|
|
BLAKE2b-256 checksum How to use checksums |
3ce50ad6d6249d18c0a7c6aae02a0aaf5a291611a494bde8d2feab3c383e7a7c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.
Transparency logRelease files / cavi_after_effects_mcp-0.1.0-py3-none-any.whl
| Download URL | cavi_after_effects_mcp-0.1.0-py3-none-any.whl |
|---|---|
| Size | 85.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1b58ca9380c5526f7d8fe9ea07aad7b313ce7e3bd072f9274530259d396e0129
|
|
BLAKE2b-256 checksum How to use checksums |
5d615ff868206bae36b383ef280148e51d34d28b229f3af76dbe332313f07d6b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.
Transparency logSecurity for cavi-after-effects-mcp 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for cavi_after_effects_mcp-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.