Skip to main content
Glama
NeuralIO444

AE Bridge MCP

by NeuralIO444
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

AE Bridge MCP

A Model Context Protocol server that lets an AI agent (Claude, or any MCP-compatible client) inspect and drive a live Adobe After Effects session — read the active composition, list selected layers, inspect a layer's transform/effects, or evaluate arbitrary ExtendScript.

Extracted from Dimension's ae_bridge_mcp/ae_eval dev tooling so other NeuralIO 444 AE-adjacent products can reuse it without depending on Dimension itself.

Part of a small set of related repos:

  • AE_Eval — the same evaluate-ExtendScript-in-AE capability as a plain terminal CLI, no MCP client needed. Independent of this repo — pick whichever fits, or use both (they share the same AE-side listener file).

  • IPC_Client — the general-purpose version of the socket transport both of the above are built on.

What it does

Four moving pieces:

  1. ae_bridge_mcp/jsx/ae_bridge_listener.jsx — loaded into a running After Effects session. Opens a TCP socket on 127.0.0.1:45445 and evaluates whatever ExtendScript it receives, using a simple length-prefixed JSON protocol.

  2. IPC_Client (a real dependency, not vendored code) — the Python-side client for that same protocol (execute_job()).

  3. ae_bridge_mcp/eval.py — evaluate() tries the socket transport first, falling back to macOS AppleScript (osascript) if the listener isn't loaded or AE isn't reachable. No CLI of its own — see AE_Eval for that.

  4. ae_bridge_mcp/server.py — the actual MCP server: a stdio JSON-RPC loop exposing 4 tools (see below) to any MCP client.

Tests in tests/.

Related MCP server: After Effects MCP Server

Tools exposed over MCP

Tool

What it does

ae_eval_script

Evaluate arbitrary ExtendScript, return the result or error.

ae_get_active_comp

Name, id, width, height, fps, duration, layer count for the active comp.

ae_get_selected_layers

Index, name, label, comment, enabled, 3D, hasVideo for every selected layer.

ae_get_layer_properties

Transform (position/scale/rotation/opacity/anchor), sourceRect, and applied effects for a given 1-based layer index.

Setup

1. Load the AE-side listener

In After Effects: File → Scripts → Run Script File... and pick ae_bridge_mcp/jsx/ae_bridge_listener.jsx. It starts listening immediately ($.global.AEBridgeListener.start() runs at the bottom of the file) and writes a confirmation line to the ExtendScript console.

To have it load automatically, drop it (or a script that $.evalFile()s it) into AE's Scripts/Startup folder for your AE version, or wire it into whatever your product's own panel/launcher already loads at boot.

To stop it: $.global.AEBridgeListener.stop(); from the ExtendScript console, or just close AE.

2. Install the Python package

pip install -e .
# or, for running tests too:
pip install -e ".[dev]"

One runtime dependency: IPC_Client (itself pure stdlib, no further dependencies) — installed automatically from its pinned commit via the git+https://... URL in pyproject.toml.

3. Point an MCP client at it

Example config (Claude Code, or any MCP client using the same command/args shape):

{
  "mcpServers": {
    "ae-bridge": {
      "command": "python3",
      "args": ["-m", "ae_bridge_mcp"]
    }
  }
}

Or run it directly to sanity-check it starts: python3 -m ae_bridge_mcp (it will sit waiting for JSON-RPC on stdin — that's expected, it's not meant to be run interactively).

This repo has no standalone CLI of its own by design — for a terminal command with the same evaluate/active-comp/selected-layers capability, install AE_Eval instead (or alongside — they share the same AE-side listener).

Transport fallback

evaluate() tries, in order:

  1. TCP socket (127.0.0.1:45445) — needs ae_bridge_listener.jsx loaded in AE. Sub-5ms round-trip. The connect phase fails fast (connect_timeout, default 2s) so an unloaded listener falls through to AppleScript quickly; the response wait itself honors the caller's full requested timeout — a legitimately slow script (many layers/effects, a render trigger) isn't cut short at 2s.

  2. AppleScript (osascript, macOS only) — works even without the listener loaded, at the cost of a slower round-trip (writes a temp .jsx file, has AE run it via DoScriptFile, reads a temp JSON output file back).

If neither works, evaluate() returns a structured error rather than hanging — check that After Effects is running and the listener is loaded.

Security

ae_bridge_listener.jsx is an unauthenticated socket — any local process that can reach 127.0.0.1:45445 and speaks the wire protocol can execute arbitrary ExtendScript through it (including filesystem access and system.callSystem()-style OS command execution) for as long as After Effects is running with the listener loaded. This is inherent to what the tool does — an AI agent is meant to evaluate arbitrary ExtendScript through it — but it's worth knowing plainly before loading it on a shared machine (a render farm node, CI runner, or multi-user workstation), where any other local process/user could reach the same port.

Testing

pip install -e ".[dev]"
pytest tests/

Tests mock the AE-facing boundary (execute_job, eval_extendscript_socket, eval_extendscript_applescript) — they don't require a real After Effects instance to run.

Known limitations

  • ae_get_layer_properties reads position/scale/etc. via .value, which reads the property at the current playhead for keyframed properties, not a deterministic rest pose. If you need a deterministic read for an animated property, evaluate a custom script via ae_eval_script instead (e.g. prop.valueAtTime(prop.keyTime(1), true)).

  • The AppleScript fallback is macOS-only; on Windows/Linux, only the socket transport is available, so ae_bridge_listener.jsx must be loaded for anything to work at all.

  • ExtendScript's return is illegal outside a function body — if you're calling ae_eval_script with a multi-statement script that needs to return a value, wrap it in an IIFE yourself: (function(){ ...; return x; })(). eval.py's own wrap_iife() helper does this for the built-in structured tools.

Changelog

  • Hardened handle_call_tool so a malformed tool argument (e.g. a non-numeric layer_index) returns an isError result instead of raising and killing the persistent stdio server process.

  • Fixed evaluate() silently capping the entire socket-transport wait at 2 seconds regardless of the requested timeout — only the connect phase is capped now (connect_timeout), the response wait honors the real request.

  • Switched to depending on the IPC_Client package instead of a vendored copy (also picks up its connect-timeout and message-size-cap fixes).

  • Fixed packaging: ae_bridge_listener.jsx moved inside the package directory and is now actually included in a built wheel/sdist — a real pip install previously shipped a package with no way to reach After Effects on Windows/Linux (only worked by accident via editable installs from a live git checkout).

  • Removed the redundant ae-eval console-script entry point (it collided with the standalone AE_Eval package's own ae-eval command if both were installed together) and the CLI code it pointed to, which fully duplicated AE_Eval.

License

MIT — see LICENSE.

Available Tools

4 tools
ae_eval_scriptB

Evaluates arbitrary ExtendScript (JSX) in Adobe After Effects and returns result or errors.

ParametersJSON Schema
NameRequiredDescriptionDefault
scriptYesThe ExtendScript (JSX) code string to evaluate.
timeoutNoEvaluation timeout in seconds (default 10.0).

TDQS

B3.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must disclose side-effect risks; it only says 'Evaluates... and returns result or errors.' It does not warn that arbitrary JSX can modify the After Effects project, invoke destructive operations, or otherwise change state. It also doesn't mention timeout behavior. The core eval behavior is named, but safety-relevant traits are absent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single sentence with no filler; the key idea (evaluates arbitrary JSX, returns result/errors) is front-loaded. It is concise and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool executes arbitrary code and has no annotations or output schema, so the description should address side effects, execution environment, and error/return format to be safe to invoke. It only covers the basic purpose, leaving important operational context missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema covers both parameters (script and timeout) at 100%, so the description need not repeat them. The description adds no parameter-level detail beyond the schema, which matches the baseline for fully documented schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Evaluates'), a specific resource ('arbitrary ExtendScript (JSX) in Adobe After Effects'), and the outcome ('returns result or errors'). This clearly differentiates from sibling getter tools by focusing on arbitrary code execution rather than predefined queries.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies general-purpose use ('arbitrary') and the sibling names suggest it complements the specific getters, but it never explicitly states when to prefer this over ae_get_active_comp or the others. No when/when-not or alternative guidance is given, leaving the agent to infer from the word 'arbitrary'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

ae_get_active_compA

Returns metadata (name, id, width, height, fps, duration, numLayers) for the active composition in After Effects.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the behavioral burden. It correctly implies a read-only operation by saying 'Returns metadata', but it does not disclose what happens when no composition is active, whether the tool requires an open project, or whether it can fail. The field list adds some useful detail, but edge-case behavior is absent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The entire description is a single front-loaded sentence that names the action, the target, and the returned fields compactly. There is no filler or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter getter with no output schema, the description is fairly complete: it lists the exact metadata fields returnedhare. Missing are failure conditions and when to use the tool, but those are minor gaps given the operation's simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parametershare, so there are no parameter semantics to document. The baseline is 4, and the description correctly adds no unnecessary parameter detail.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Returns metadata') and the specific resource ('active composition in After Effects') while enumerating the exact fields returned. This makes it easy to distinguish from sibling tools that operate on selected layers or evaluate arbitrary scripts.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no guidance on when to choose this tool over the sibling tools, such as ae_get_selected_layers or ae_get_layer_properties. It does not mention exclusions, prerequisites, or alternative conditions, leaving the agent to infer usage solely from the name.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

ae_get_layer_propertiesA

Returns transform coordinates, bounding box sourceRect, and applied effects list for a specific layer index in the active comp.

ParametersJSON Schema
NameRequiredDescriptionDefault
layer_indexYes1-based layer index in active comp.

TDQS

A3.7/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the burden. It discloses what data is returned (transform, sourceRect, effects list) but does not mention potential errors for invalid layer_index, whether the active comp must exist, or if the operation is read-only. It is a read operation by nature, but the description doesn't explicitly state side effects or failure modes.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, well-structured sentence that front-loads the key outputs and specifies the target layer. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter read tool, the description is mostly complete. However, it lacks details about error handling (e.g., out-of-range layer_index), whether the active comp is required, and the exact structure of the returned data. Since there is no output schema, a bit more detail on return format would improve completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%: the only parameter, layer_index, is described as '1-based layer index in active comp.' The description adds context about what the parameter is used for (specific layer index) but doesn't add meaning beyond the schema. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific verb 'Returns' and the resource: transform coordinates, bounding box sourceRect, and applied effects list for a specific layer index in the active comp. It distinguishes itself from sibling tools like ae_get_active_comp and ae_get_selected_layers by focusing on layer properties at a given index.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage: call this when you need transform, bounding box, or effects data for a specific layer index. It does not explicitly state when to use alternatives like ae_get_selected_layers (for selected layers) or ae_get_active_comp (for comp info), but the context signals and sibling names make the distinction reasonably clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

ae_get_selected_layersA

Returns currently selected layers in the active comp with indices, names, comments, and labels.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool 'returns' data, implying a read-only operation, but does not explicitly confirm non-destructiveness, potential errors, or whether the active comp is required to have a selection. This minimal disclosure is a gap for a tool without annotation safety hints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that front-loads the action and resource, then enumerates the specific return fields. There is no redundant or extraneous content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple, parameterless tool with no output schema, the description covers the essential purpose and fields. It does not specify the return structure (e.g., array vs. object) or error handling, but given the low complexity, this is a minor omission.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the schema fully covers them (vacuously). Per the rubric, 0 parameters warrants a baseline of 4. The description adds no parameter details because there are none to describe.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description specifies the exact action ('Returns'), the resource ('currently selected layers in the active comp'), and the detailed fields ('indices, names, comments, and labels'). It clearly differentiates from siblings like ae_get_active_comp and ae_get_layer_properties by focusing on the selection set.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The usage is implied: it returns selected layers, so an agent would use it when needing that data. However, there is no explicit guidance on when to prefer this over the sibling tools or any exclusions, leaving selection context implicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updatesv1.0.0
    • First observedae_eval_script
    • First observedae_get_active_comp
    • First observedae_get_layer_properties
    • First observedae_get_selected_layers
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.6/5.0

Scored across 4 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: evaluation of scripts, retrieval of active comp metadata, retrieval of selected layers, and retrieval of specific layer properties. There is no semantic overlap between these operations, making selection unambiguous.

Naming Consistency3/5

All tools use a consistent 'ae_' prefix followed by a verb-object pattern (e.g., 'eval_script', 'get_active_comp'), which is good. However, 'ae_get_selected_layers' and 'ae_get_layer_properties' could be more consistent in verb ordering, though the naming is still readable and predictable.

Tool Count4/5

With 4 tools, the server is on the minimal side but still reasonable for a specialized After Effects bridge. It covers the essential read and evaluation operations without bloat, though a few more tools could enrich the surface.

Completeness2/5

The server provides read-only access (evaluation, comp metadata, layer selection, layer properties) but lacks any modification or creation tools (e.g., add layer, set property, render comp). This leaves a significant gap for an automation server, as agents cannot perform common After Effects scripting tasks beyond evaluation and inspection.

Maintenance

ActivityMaintained
ResponsivenessResponsive

Resources

Related MCP Connectors

Related MCP Servers