Surehand MCP for Adobe After Effects

Add a layer to a composition: solid, text, shape (empty, use ae_add_shape to draw), null, adjustment, camera, light, or an existing project item (footage/comp).

Draw a shape (rectangle, ellipse, polygon, star, or custom path) with fill and/or stroke, on a new shape layer or an existing one. Positions are relative to the layer (new layers are centered in the comp).

Apply an effect to a layer by match name (preferred, e.g. "ADBE Gaussian Blur 2", "ADBE Fill", "ADBE Glo2", "ADBE Drop Shadow") or display name, optionally setting parameters. Returns the effect's parameters.

Run many steps in ONE call: each step is a tool with its arguments (any project/comp/layer/property/keyframe/effect/text/footage tool) or {tool: "ae_run_script", args: {code}}. All steps form a single undo step and return one change report. Atomic by default: if any step fails, everything is undone and you get the error of the failing step. Use it for repetitive or multi-part edits (e.g. style 30 layers, build a scene) to save round trips.

Run any After Effects tool by name with its arguments, e.g. tools listed by ae_tools that aren't loaded in this chat. Same validation, permissions, change report and activity log as calling the tool directly. Get the parameters with ae_tools {describe: [name]}.

Safety copies of the project: save (saves the open project, then keeps a timestamped copy), list the checkpoints of this project, or restore one (opens it as a NEW file next to the original; neither the original nor an earlier restore is ever overwritten). Use before large or risky changes.

Create a new composition and (by default) open it in the viewer.

Search every layer of a comp (or one layer) for properties whose name or match name contains the query, e.g. "opacity", "blur", "Source Text", "ADBE Fill Color". Returns ready-to-use paths. Filter to animated or expression properties.

Composition settings plus a summary of its layers (index, id, name, type, timing, parent, switches). Large comps are paged: use layerOffset/layerLimit (see totalLayers / nextLayerOffset in the result).

Overview of how a composition is built: the tree of nested precomps (with how many times each is used), parenting chains, track mattes, and which layers/comps each expression references. Use it to understand an unfamiliar project before editing.

List an effect's parameters (names, match names, value types, defaults, min/max) WITHOUT changing your layers, so you know the exact parameter names for ae_apply_effect / ae_set_effect_params. Pass comp+layer to inspect an effect already applied (current values).

Exact on-screen bounding boxes of layers in composition pixels at a time, after all transforms, parenting, 3D and the active camera (via AE's own toComp()). Also reports whether each layer is visible at that time, fully/partly/not in frame, and inside action-safe (5% margin) and title-safe (10% margin). Use it to check alignment, spacing, overlaps and safe areas with numbers.

Full info for one layer: switches, timing, parent, source, transform values, effects, masks count, markers, text, and every animated/expression property.

Summary of the open project: file path, dirty state, item counts, bit depth, render queue size, active item.

Inspect the property tree of a layer (or a sub-group via path): names, match names, values, keyframe counts, expressions. Use this to discover property paths before setting values.

Returns the After Effects ExtendScript cheat sheet (ES3 rules, helpers, common match names). Read before writing complex ae_run_script code.

What the user has selected: project items, and in the active comp the selected layers and selected properties (with paths).

List the user's own After Effects scripts: AE's Scripts folder (and ScriptUI Panels) plus folders configured as "scriptFolders" in ~/.surehand/ae/config.json, with each script's description from its header comment. Run one with ae_run_script_file.

Prove a structural change (un-precompose, bake expressions, reorder effects, simplify a rig) left the render unchanged, or show which frames and areas differ. capture: render reference frames (default: active comp, 5 frames over the work area), returns a proof id. compare: render them again and compare pixel by pixel (verdict, per-frame max difference, changed pixels, ΔE, area, difference image). run: capture, ae_batch steps, compare, in one call. For un-precompose, prove the parent comp. Only the sampled video frames are compared (alpha included; not audio, the comp background color or times between samples; 32 bpc values above 1.0 are clamped).

Render several frames of a composition into ONE image (a grid, each cell labelled with its time and frame number), so you can judge motion, timing and easing, not just a single frame. Defaults to 9 frames spread over the work area.

Render a frame of a composition and return it as an image, so you can SEE the result. Inspection options: zoom into a region, render only some layers, show transparency on a checkerboard or a color, and compare against another time or comp as a difference image (black = identical). Large frames are downscaled to maxSize.

Execute JavaScript inside After Effects (its ExtendScript scripting API) and return the result. This is the most powerful tool: anything in the After Effects scripting API is available (app, app.project, CompItem, layers, properties, render queue, File/Folder, system.callSystem...). - The code runs as the body of a function: use `return value` to send data back. Returned AE objects (comps, layers, properties, items) are summarized to JSON automatically. - `args` (the JSON you pass in `args`) and `log(...)` are available; log output is returned too. - Modern JavaScript is fine: let/const, arrow functions, template strings, destructuring, spread, classes, ?. and ??, for...of, plus map/filter/forEach/find/includes, Object.keys/assign and JSON (converted for AE automatically). Not available: async/await, Promise, Map/Set, generators. - The `aemcp` helper library is available: aemcp.findComp(idOrName), aemcp.findLayer(comp, indexOrName), aemcp.findItem(ref), aemcp.resolveProp(layer, 'Transform/Position'), aemcp.color('#ff0000'), aemcp.compInfo(comp, true), aemcp.layerInfo(layer, true), aemcp.propInfo(prop, {depth:2}), aemcp.projectInfo(). - Collections are 1-based: app.project.item(1), comp.layer(1), prop.property(1). - The whole script is one undo step. Errors come back with the failing line and code around it. ae_get_scripting_guide has an API cheat sheet.

Run an existing .jsx/.jsxbin script file from disk inside After Effects (like File > Scripts > Run Script File). `args` is exposed to the script as the global AEMCP_ARGS. Returns the value of the script's last expression.

Set (or clear with an empty string) an expression on a property. Returns any expression error AE reports.

Create keyframes on a property in one call, with optional interpolation (linear/bezier/hold) and temporal easing. Place keys by time (seconds) or frame (whole frames). Example: path "Transform/Position", keyframes [{time:0,value:[0,540]},{frame:24,value:[960,540],easeIn:80}].

Set the value of any property (transform, effect parameter, shape attribute, text...). If `time` is given (or the property already has keyframes) a keyframe is set at that time. Examples: path "Transform/Opacity" value 50; "Transform/Position" [960,540]; "Transform/Scale" [50,50]; "Effects/Fill/Color" "#ff0000".

Check the connection to After Effects: app version, OS, open project, active item, permission mode, and whether AE is busy. Lists every running After Effects instance when several are open; pass `instance` (e.g. "2025", "2026" or a port) to choose which one this session controls. Call this first if unsure AE is reachable.

Discover every After Effects tool, including ones not loaded in this chat: list them by category (one line each), or describe chosen tools (full parameters). Then run any of them with ae_call. Categories: status & app, scripts, project, comps, layers, properties & keyframes, effects, shapes & masks, text, 3D, audio, footage, files & export, checks, see & measure, essential graphics, render.

Undo the last action(s) in After Effects (Edit > Undo).