AE Motion MCP
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| AE_AERENDER | No | Full path to aerender if auto-detection fails. | |
| AE_MCP_ALLOW_JSX | No | Set to 1 to enable run_jsx. | |
| AE_MCP_BRIDGE_FILE | No | Override the bridge file (default ~/.ae-motion-mcp/bridge.json). This must also be set for the panel's environment if you change it. | |
| AE_MCP_ALLOWED_DIRS | No | Folders (separated by the OS path delimiter, ":" or ";") that tools may read from and write to. Default: your home folder. The temp folder is always allowed. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Controls a live Adobe After Effects project. Start with get_project: every comp with its layers (ids, names, kinds, timing). Check visuals with preview_frame (several times in one call give one tiled image). The motion-guide prompt has the build loop. Work fast: make independent calls together in one turn; put dependent steps in one batch call ("$1.id" uses step 1's result). Results already show the outcome (keys as set, values read back, fields changed), so don't re-read to confirm. Units: seconds, pixels, colors [r,g,b] 0-1, scale in percent, degrees. x right, y DOWN, z into the screen (a camera in front of the comp has negative z). Comps, layers and items are project-wide numeric ids, not layer indexes. Unknown argument keys are rejected. Properties: an alias (position, scale, rotation, opacity, anchor; x_position / y_position / z_position after set_layer separate_dimensions; volume = audio levels in dB) or a path of match names and 1-based indexes, e.g. ["ADBE Effect Parade", 1, "ADBE Gaussian Blur 2-0001"]; list_properties shows them. Layer edits return {id, index, name}; results leave out defaults: a missing flag is false (locked, shy, solo, three_d, motion_blur, comp motion_blur / frame_blending), blend_mode NORMAL, stretch 100, enabled true, no parent, square pixels, work area = whole comp, shutter only with motion blur on. get_comp lists layers top first; a missing in is 0, out the comp's end, start equal to in. Work like a senior motion designer and video editor. S = the comp's short side (1080 for 1920x1080, 1080x1920, 1080x1080):
Format: 16:9 for screens and YouTube, 9:16 for Reels/TikTok/Shorts, square or 4:5 for feeds. Vertical: stack top to bottom, main content in the middle 60% of the height, no text in the top 10%, bottom 20% (app UI) or 5% at the sides. Elsewhere text stays in the 5% title-safe margin.
Copy exactly as given (words, case, punctuation); no all caps unless asked.
Type: headlines 10-18% of S, bold or semibold; supporting lines at least half the headline and 3.3% of S; lower-third names 5.5-6.7% of S, titles 3-3.7%; captions 4.5-6%. Wide tracking only on small labels.
Layout: one focal point; centre the whole group's visual weight; groups span 40-70% of the width (85% in vertical); align to shared edges or centres.
Timing: something moves within 0.2 s; entrances 0.4-0.7 s, decelerating (snappy or spring), staggered 0.05-0.12 s; build done by about 40% of a short piece; exits accelerate and run 0.3-0.45 s.
Holds never freeze: a slow push (3-6% over the hold) on the main element or a parent null, or drift.
Polish: backgrounds with depth (gradient, vignette, soft glow; not flat black or white unless asked); soft-edged glows and shadows (blur or a layer style, never a hard box); one accent colour, sparingly; shapes draw on (trim paths) or grow from an edge rather than fade; consistent corner radii.
Footage: cut on action or the beat (beat_markers, align_to_markers); shots at least about 1.5 s, longer with text; vary lengths; open strong (social: a hook in 1-2 s); trim dead air (split_layer, delete_range ripple); b-roll over jump cuts; mostly hard cuts, transitions only where the scene changes. Fill the frame unless letterboxing is asked; scale footage at most about 120%; for vertical, scale landscape to fill the height with the subject centred.
Text over video: a soft shadow, outline or translucent box on busy footage; social captions 1-2 short lines timed to the speech, high contrast, in the safe area.
Sound: dialogue first; duck_music under voice-over; effects 6-12 dB below the music (add_sfx); social delivery about -14 LUFS (render_start deliver).
Counting animations only for plain numbers (not 24/7).
Before finishing: run review_motion and fix every warning, then preview_frame at 6-9 times: readability, margins, contrast, framing, nothing frozen or clipped. run_jsx is a last resort: use a dedicated tool whenever one exists (list_properties / add_property / set_property reach almost any property), and only fall back to run_jsx for something no tool covers. More tools, not listed yet (to keep every request small): timeline: split_layer, shift_layers, sequence_layers, delete_range, insert_time, trim_comp, set_playhead, add_marker, update_marker, align_to_markers, list_markers, delete_marker; masks: add_mask, set_track_matte; scene3d: get_camera, set_camera, camera_move, camera_shake, camera_rig, set_3d, set_light, set_3d_view; design: align_layers, set_anchor, add_shape, text_to_shapes, add_layer_style; audio: beat_markers, audio_react, find_sound_cues, add_sfx, duck_music; scripting: run_jsx. Use one as a batch step and its group is listed first (its arguments follow the tool's usual schema), or call load_tools to see the arguments.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
| prompts | {
"listChanged": true
} |
| resources | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| get_projectA | List project items with each comp's layers (id, name, kind, timing; left out when the page has over 300 layers: layers_listed false, use get_comp), the active comp id, AE version and project path. Filter by name (substring) or type; page with limit (200) / offset. If a newer ae-motion-mcp is known, an update field says how to update: tell the user. |
| get_compA | Get composition settings and its layers, top first (id, name, kind, non-default in/out/start, parent, blend mode, flags). Big comps: filter by name (substring), kind or at (seconds: layers visible then), page with limit (default 150) / offset; kinds counts all layers. |
| get_layerA | Get a layer (or several: layer_ids): transform values, text, effects, expressions, marker count, masks, track matte, bounds (content: its layer-space box; comp: its place in the comp, null for 3D). Values at |
| list_propertiesA | Walk a layer's property tree and return names, match names, value types, values, keyframe counts and expressions. Use it to find property paths before set_property / set_keyframes. |
| get_keyframesA | Read the keyframes of one property: time, value, in/out interpolation and temporal ease, plus any active expression; unanimated, its value. Returns every key that fits; next_offset when there are more (offset continues; limit caps a page). Use list_properties to find the path. |
| find_effectsA | Search installed effects by display name, match name or category. Page: limit (50) / offset; matched and next_offset when there are more. |
| save_projectA | Save the project. With path it does Save As (.aep or .aepx, inside the allowed folders; pass overwrite to replace an existing file). Without path it saves in place, which needs a project that has been saved once. render_start needs a saved project. clean: true first removes footage no comp uses (removed_footage counts it). snapshot: true also keeps a numbered copy in snapshots/ next to the project (note labels it); open_project on that copy goes back to it exactly. |
| open_projectA | Open an After Effects project (.aep or .aepx, inside the allowed folders), or new: true for an empty one, replacing the open one. If the open project has unsaved changes it refuses, unless discard_unsaved is true (those changes are then lost; use save_project first to keep them). Returns the new project like get_project. Cannot be undone. |
| create_compC | Create a composition and open it in the viewer. |
| set_compB | Change comp settings; only the fields you pass change. work_area must fit inside the comp. motion_blur and frame_blending are the comp switches the layer switches need to render; shutter_angle default 180. |
| import_footageA | Import a file, or several (paths), into the project. as: sequence (path is its first frame), comp / comp_cropped (a layered PSD or Illustrator file as a comp of its layers). fps, loop and alpha set the footage's interpretation (set_item changes them later). folder files the imports. All files are checked before any is imported. |
| set_itemA | Change a project item (comp, footage or folder): name, comment, label (0-16), folder (null: top level); footage interpretation (fps, loop, alpha); file swaps the footage's file for every layer that uses it (sequence: file is a sequence's first frame). |
| delete_itemA | Delete a project item (comp, footage or folder) by id. Refuses items that are used in comps, and non-empty folders, unless force is true (force also deletes the layers that use the item). |
| add_layerB | Add a layer. item_id: footage/precomp source. center: camera/light. position with 3 values turns 3D on. box_size: box text; text_style as set_text. anchor moves the anchor onto the content (as set_anchor) before position, so position places e.g. the text's center. shape: a shape layer's first shape (as add_shape). mesh: a 3D primitive, centred on position, color is its base color (After Effects 26.3+; moves the comp to the renderer that draws meshes, reported as renderer_changed; list_properties has its size, bevel and slices). fit_to (shape): a rect that keeps fitting that layer's content + padding (a highlight behind text). fit: scale to cover or fit inside the comp frame. Timing: in/out are comp times; source_in is the source time shown at in (no start maths); stretch in percent (200 = half speed). |
| set_layerA | Edit a layer; only the fields you pass change. stretch: percent (200 = half speed, negative reverses). parent_id null unparents. blend_mode: e.g. ADD, SCREEN. motion_blur / frame_blending need the switch in set_comp too. separate_dimensions: x_position / y_position / z_position. auto_orient path: along the motion path. collapse: continuously rasterize. guide: not rendered. sampling bicubic: sharper scaled images. solid_color / solid_size change the solid item (every layer using it). audio_fade: seconds of equal-power fade from the in point / to the out point (volume keys; works under duck_music). |
| link_layersA | Parent layer_ids to parent_id (null unlinks), or to a new_null created at their average position (3D if any of them is), stacked above them. jump true keeps each child's own transform values (it can visibly move). Self-links, cycles, locked layers or mixed comps are refused before anything changes. |
| replace_sourceA | Swap the footage, comp or solid a layer shows for another project item (like Alt/Option-dragging onto it), keeping the layer's timing, keyframes, masks and effects. fix_expressions (default true) updates expressions that referred to the old source. Works on footage, precomp, solid and null layers. |
| delete_layerC | Delete a layer. |
| duplicate_layerA | Duplicate a layer (the copy sits above the original). count makes several copies; offset_seconds shifts copy N later in time by N * offset_seconds. |
| reorder_layerA | Change a layer's stacking order. Pass exactly one of: to, index (1 = top), before_layer_id, after_layer_id. Before means above in the stack. |
| precomposeA | Precompose layers from the same comp into a new comp. move_attributes (default true) moves their transforms, effects and masks into the new comp; false ("leave all attributes", one footage, solid or precomp layer only) keeps them on the layer in the current comp. |
| set_propertyA | Set a static value, or a value at |
| set_keyframesA | Replace all keys on a property (merge: keep keys at other times; replaced: old keys removed). Path properties (ADBE Mask Shape, ADBE Vector Shape) take a shape spec as v; keep the vertex count the same across keys for clean morphs. interp spring/bounce springs the segment to the next key (works on any property). Fails if another expression is active. Returns the keys as set. |
| edit_keyframesA | Edit single keys on one property, in order, leaving the others. Address a key by t (within half a frame) or index (1-based). set creates a key at t (v or the current value) or updates one; spatial_in/out are motion-path tangents relative to the key. move keeps every setting. Returns the edited keys (get_keyframes lists all). |
| copy_animationA | Copy a property's keys (with easing and tangents) or static value, plus any expression, to other layers, replacing their keys. to_path targets another property of the same type. offset_seconds shifts the keys; the i-th target also gets i * stagger_seconds. |
| add_propertyB | Add a property or group that set_property cannot reach until it exists. Text animator: group_path ['ADBE Text Properties','ADBE Text Animators'], match_name 'ADBE Text Animator'; then add properties under returned path + 'ADBE Text Animator Properties' (e.g. ADBE Text Opacity, ADBE Text Position 3D, ADBE Text Fill Color) and a selector under returned path + 'ADBE Text Selectors' (ADBE Text Selector). Returns the new property path. |
| set_expressionA | Set an expression on a property (empty string clears it), on one layer or the same property of many (layer_ids: send a shared expression once). Returns whether After Effects accepted the syntax. |
| apply_effectB | Add an effect by match name (see find_effects) and set parameters by name, match name or 1-based index. If any parameter fails the effect is removed. |
| edit_effectA | Remove, enable or disable an effect on a layer by its 1-based index (see get_layer for the list), or set: change params as in apply_effect (all checked first). |
| apply_presetB | Apply an .ffx animation preset to a layer. Path must be inside the allowed folders. |
| set_textA | Set text and styling on a whole text layer; only the fields you pass change, read back in the result (skipped: what After Effects refused). font: PostScript name (find_fonts). leading turns auto leading off; stroke_color turns the stroke on; horizontal/vertical_scale in percent. box_size resizes box text (point text cannot become box text: add_layer options.box_size). time sets a keyframe. ranges style part of the text after the whole-layer fields (AE 24.3+): match (every occurrence of a string) or start/end (character indexes from 0, end exclusive, default the end). New text clears earlier part styling (ranges_cleared): pass ranges in the same call. |
| find_fontsA | Search the installed fonts by family, style or PostScript name (e.g. "montserrat", "bold italic"); returns PostScript names for set_text font. Needs After Effects 24.0+. |
| get_textA | Read a text layer's content and styling (font, size, colors, stroke, leading, tracking, scale, caps, indents, justification, box size), at |
| staggerA | Offset existing keyframes of one property across layers: layer i is shifted by i * offset_seconds. Every key setting (easing, motion-path tangents) is kept. Moves keys, not layers (whole layers: shift_layers / sequence_layers). |
| add_shape_modifierA | Add trim_paths, repeater or round_corners to a shape group (group_index, default 1). params maps property names or match names to values. Returns the modifier's path and property names for set_keyframes. |
| animateA | Animate layers with a named move, keyed from their current values. In/out: fade, pop (scale from 0), grow (from 80%), slide (direction of travel, default up), drop, spin; style snappy (default), smooth, spring (default pop/spin), bounce (default drop), linear; exits accelerate; springs are expressions on the keys; time defaults to the in point (out: out point - duration). Through a hold, so the frame never freezes: push (slow scale-up by amount %, default 4) and drift (slow float by distance px, default 2% of the comp height, toward direction); they start where the layer's animation lands (keeping its landing ease) and run to its out point; style smooth (default) or linear. Layer i starts i * stagger later. |
| text_revealB | Reveal (phase out: hide) a text layer unit by unit (text animator + expression selector). Each unit takes duration and starts stagger after the previous. mask clips rise/drop at a line so letters slide out from behind it. Returns the end time. |
| transitionC | Add a shape transition on top that covers the frame at time (cut scenes there) and clears by time + duration/2: wipe, bars (staggered stripes) or iris (disc grows, then opens from its centre). |
| review_motionA | Critique a comp's animation without rendering (cheap, no image): linear easing, holds over max_hold (changes too small to see don't count as motion: fix holds with animate push / drift), a first move later than 0.3 s, layers moving in unison, entrances with no animation, moves cut off by out points, jumps, text under min_text px (default 3% of the comp's short side), share of moves on beat markers; layers hidden behind opaque ones (3D: by depth), off screen, a background that stops filling the frame, text partly covered, text crossing the 5% title-safe margin (vertical comps: the top 10% and bottom 20% social apps cover) (scene false skips). Run after each scene and fix every warning. |
| preview_frameA | Render comp frames and return them as one image (several times are tiled left to right, top to bottom). Images cost tokens by size: keep the default size, and pass several times in one call rather than calling once per time. In an edit, scene / scenes name the precomp each frame shows. |
| render_startA | Save the project (saved once before) and start a background aerender job; poll render_status with the job_id. om_template / rs_template: output-module / render-settings template names (the output module picks the file extension). software: Mercury Software Only (fixes GPU failures). With ffmpeg the result is checked (black/frozen/silent spans, loudness; verify false skips); deliver: H.264 MP4 at loudness (-14 LUFS); audio_only: the mix. Renders the whole comp (not the work area); start / end (s) a part, draft: true a fast low-quality look at the motion. |
| render_statusB | Get state (running|done|failed|canceled), percent, frames, eta_s, poll_after_s (wait that long), phase, check (issues in the file), errors + hint, log tail, file written. |
| render_cancelC | Cancel a running render job. |
| check_for_updatesA | Check whether a newer ae-motion-mcp release exists (GitHub version tags). Returns current and latest versions, update_available and, if so, how to update. Uses a result cached for a day unless force is true. Disabled when AE_MCP_UPDATE_CHECK=0. |
| batchA | Run up to 50 tool calls in order in one call (prefer it for multi-step builds). "$N.path" in args is that value from step N's result (from 1), e.g. "$1.id", "$2.layers.0.id"; name a step (as: "title") to use "$title.id" instead. "$$" is a literal $ ("$$99"). defaults: {tool: args} merged under every step of that tool (shared style, comp_id). All steps are checked before any runs; a step that fails in After Effects stops the batch with the results so far and a batch_id for resume. Each step is its own undo step. Not preview_frame, run_jsx or open_project. |
| load_toolsA | Show a tool group that is not listed yet, to see its tools' arguments: project (comps, import, open/save, delete items); layers (add/set/duplicate/delete/reorder/link layers, precompose, replace source); timeline (split, shift, sequence, trim, insert/delete time, markers); masks (masks, track mattes); animate (properties, keyframes, expressions, effects, presets, text, stagger, shape modifiers); motion (animate (named moves with springs), text_reveal, transition, review_motion); scene3d (3D layers, cameras, lights, camera moves/rigs/shake, 3D views); design (align, anchors, add shapes, layer styles, text to shapes); output (preview_frame, renders); audio (beat markers, audio-reactive expressions, sound-effect cues and placement); scripting (run_jsx (also needs AE_MCP_ALLOW_JSX=1)). A batch step naming one of their tools shows its group by itself. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
| motion-guide | Conventions and the recommended build loop for motion graphics |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
| project | Current project summary |
| selection | Layers selected in the active comp |
TDQS
Scored across 46 tools
Most tools target a clearly distinct resource+action (set_property vs set_keyframes vs edit_keyframes vs copy_animation are explicitly delimited, and get_text/get_layer/list_properties are separated by granularity). A few pairs need reading the description to separate (get_comp vs get_project vs get_layer, apply_effect vs edit_effect vs apply_preset), but the descriptions disambiguate them and set_property even points to set_text for text.
Consistent snake_case with a mostly verb_noun shape (get_layer, set_keyframes, delete_item, render_start, find_fonts). A handful are bare verbs or verb-object without a resource noun (precompose, stagger, animate, transition, batch), which is readable but a minor deviation from the dominant pattern.
46 exposed tools is well above the comfortable range for a single server surface, even for a large domain like After Effects automation. The load_tools progressive-disclosure groups mitigate this somewhat by deferring timeline, masks, scene3d, audio and scripting tools, but the top-level set is still heavy and increases selection cost.
Core lifecycle is covered end to end: projects (open/save/import), comps, layers, properties, keyframes, expressions, effects, text, previews and renders with polling/cancel. Gaps are minor and mostly deferred rather than missing (splitting, masks, cameras/lights, markers, audio live in load_tools groups), and there is no top-level undo control.