# ease-ae-mcp

**Control Adobe After Effects from Claude — with real keyframes, real easing, and a way for the AI to check its own work.**

Built and used in-house at [ease Production](https://ease-pro.net), a motion graphics and animation studio in Muscat, Oman. Based on the open-source [after-effects-mcp](https://github.com/Dakkshin/after-effects-mcp) by Dakkshin (MIT).

[العربية ↓](#بالعربي)

---

## What's different from the original

The original server can create comps and layers and set simple keyframes. We needed the AI to animate the way an animator does, so we added:

| Tool | What it does |
|---|---|
| `run-jsx` | Runs any ExtendScript with the **AK toolkit** preloaded (comp/layer/property lookup, shape builders, effect controls). Errors come back as `{error, line}` instead of a silent failure. |
| `set-keyframes` | Pose-to-pose keyframes with **temporal ease** (speed + influence), presets (`easy`, `soft`, `strong`, `snap`, `whip`…), hold/linear/bezier, and **spatial tangents** for arcs. |
| `batch-keyframes` | Many properties on many layers in a single round-trip. |
| `apply-tracks-file` | Applies a whole JSON "dope sheet" from disk. |
| `get-keyframes` / `sample-values` | Reads keys back and samples evaluated values, so the AI can verify curves numerically. |
| `inspect-comp` | Layers, parenting, effects, keyed properties and expressions in one call. |
| `motion-check` | Flags frames where position acceleration spikes — finds pops and broken contacts. |
| `save-frames` | Renders PNG stills so the AI can **look** at the result. |
| `render-comp` | Renders to MP4 and waits for it. |
| `save-project`, `import-file` | Save, and import PSD/AI as layered comps. |

All original tools (`create-composition`, `apply-effect`, `apply-effect-template`, `setLayerKeyframe`, `setLayerExpression`, …) are still there.

## Install

### Option A — one click (Claude Desktop)

1. Download **`ease-ae-mcp.mcpb`** from the [latest release](../../releases/latest).
2. Double-click it, or drag it into Claude Desktop → Settings → Extensions, and click **Install**.

No Node.js or terminal needed — Claude Desktop runs it.

### Option B — from source

```bash
git clone https://github.com/itareq92/ease-ae-mcp.git
cd ease-ae-mcp
npm install        # also builds
```

Then add to your MCP client config (e.g. `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "ease-ae-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/ease-ae-mcp/build/index.js"]
    }
  }
}
```

### Then, in After Effects (both options)

1. **Edit → Preferences → Scripting & Expressions** (macOS: *After Effects → Settings*) → enable **Allow Scripts to Write Files and Access Network**.
2. Open the bridge panel:
   - **Quick:** *File → Scripts → Run Script File…* → `Documents/ae-mcp-bridge/mcp-bridge-auto.jsx` (the server copies it there the first time Claude starts it).
   - **Permanent:** run `node install-bridge.js` as administrator, restart AE, then *Window → mcp-bridge-auto.jsx*.
3. Keep the panel open with **Auto-run commands** ticked.

Ask Claude something like: *"Create a 1920×1080 comp called Intro, add a ball, and make it bounce three times with proper squash and ease. Then save frames at 0.5s, 1s and 1.5s so you can check it."*

## How it works

Claude ⇄ MCP server (Node) ⇄ JSON files in `Documents/ae-mcp-bridge/` ⇄ bridge panel inside After Effects.

The panel polls for a command file, runs it inside one undo group, and writes the result back. That's why the panel must stay open.

## Support & safety

- **Provided as-is, without support.** Please report bugs through [GitHub Issues](../../issues), not DMs — that way every answer helps everyone.
- `run-jsx` executes arbitrary ExtendScript in After Effects with file and network access. Only use it with clients and prompts you trust, and save your project before long sessions.
- Developed and used daily on After Effects 2025 for Windows. macOS should work but has not been tested by us.

## Credits & license

- Original server: [Dakkshin/after-effects-mcp](https://github.com/Dakkshin/after-effects-mcp)
- Extensions (AK toolkit, keyframe/review/render tools, packaging): Tareq Al-Rubaie / ease Production
- MIT — see [LICENSE](LICENSE).

---

<div dir="rtl">

## بالعربي

**تحكّم في أفتر إفكتس من Claude — بكي فريمز حقيقية وإيزنق حقيقي، ومع أدوات تخلي الذكاء الاصطناعي يراجع شغله بنفسه.**

هذي الأداة نستخدمها داخلياً في [ease Production](https://ease-pro.net)، استوديو موشن جرافيك وأنيميشن في مسقط. مبنية على المشروع المفتوح [after-effects-mcp](https://github.com/Dakkshin/after-effects-mcp) لـ Dakkshin (رخصة MIT).

### وش الإضافات

النسخة الأصلية تسوي كومبوزيشن وطبقات وكي فريمز بسيطة. احنا كنا نحتاج الذكاء الاصطناعي يحرّك مثل ما يحرّك الأنيميتر، فأضفنا:

- **`set-keyframes` و `batch-keyframes`**: كي فريمز بإيزنق زمني (سرعة + تأثير) وقوالب جاهزة، ومسارات منحنية للحركة.
- **`run-jsx`**: يشغّل أي سكربت ExtendScript ومعه مكتبة AK جاهزة، وإذا صار خطأ يرجع لك رقم السطر.
- **`get-keyframes` و `sample-values` و `inspect-comp`**: يقرأ الحركة ويتأكد منها بالأرقام.
- **`motion-check`**: يطلع لك الفريمات اللي فيها قفزة أو نطّة غلط في الحركة.
- **`save-frames`**: يصدّر صور ثابتة عشان Claude **يشوف** النتيجة ويعدّلها.
- **`render-comp`**: يرندر MP4 وينتظر لين يخلص.

### التثبيت

**الطريقة الأسهل (Claude Desktop):**

١. حمّل ملف **`ease-ae-mcp.mcpb`** من [آخر إصدار](../../releases/latest).
٢. افتحه بضغطتين، أو اسحبه إلى Claude Desktop ← Settings ← Extensions واضغط **Install**.

ما تحتاج Node.js ولا ترمنال.

**بعدها داخل أفتر إفكتس:**

١. Edit ← Preferences ← Scripting & Expressions، وفعّل **Allow Scripts to Write Files and Access Network**.
٢. File ← Scripts ← Run Script File… واختر الملف `Documents/ae-mcp-bridge/mcp-bridge-auto.jsx`.
٣. خل اللوحة مفتوحة وخيار **Auto-run commands** مفعّل.

جرّب تقول لـ Claude: *"سوّ كومب 1920×1080 اسمه Intro، وحط كرة تنط ثلاث مرات بسكواش وإيزنق صح، وبعدين صدّر فريمات عند 0.5 و1 و1.5 ثانية وراجعها."*

### الدعم

- الأداة مقدّمة **كما هي وبدون دعم فني**. أي مشكلة اكتبها في [GitHub Issues](../../issues) مو في الخاص، عشان الجواب يفيد الكل.
- أداة `run-jsx` تشغّل أي كود داخل أفتر إفكتس، فاحفظ مشروعك قبل الجلسات الطويلة.

</div>