# After Effects MCP Server

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/badge/Node.js-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
[![Model Context Protocol](https://img.shields.io/badge/MCP-Compatible-blue.svg)](https://modelcontextprotocol.io/)

A standalone, local-first **Model Context Protocol (MCP)** server that enables AI assistants (such as Claude Desktop, Cursor, ChatGPT MCP clients, and Antigravity) to directly command and automate **Adobe After Effects 2026** (with support for 2025/2024) through validated, type-safe tools.

---

## Architecture Overview

```
AI Client (Claude / Cursor / MCP Client)
               │ (Standard MCP stdio Transport)
               ▼
       MCP Server Protocol Layer
               │ (Zod Schema Validation & Permission Policy)
               ▼
       Application Services Layer
               │ (Sequential FIFO Command Queue)
               ▼
       ExtendScript Bridge Adapter
               │ (Atomic JSX Execution via AfterFX.exe -r)
               ▼
      Adobe After Effects 2026
```

---

## Key Highlights

- **Standard MCP Protocol:** Exposes 34 production-ready tools, 8 resources, and 6 prompts via standard `stdio` transport using the official `@modelcontextprotocol/sdk`.
- **ExtendScript Execution Bridge:** Dispatches commands directly to Adobe After Effects (`AfterFX.exe -r`) with atomic JSON result reading and `app.beginUndoGroup()` undo protection.
- **Dual Mode (Host + Simulation):** Automatically detects `AfterFX.exe` in standard Windows installations. If After Effects is not installed or `AE_MOCK_MODE=true` is set, runs in high-fidelity simulation mode for testing and CI/CD pipelines.
- **Defensive Security:**
  - Path traversal protection and path normalization.
  - Risk classification (**LOW**, **MEDIUM**, **HIGH**).
  - Explicit `approvalToken` required for destructive operations (`composition.delete`, `project.close`, `layer.delete`).
  - No arbitrary JSX execution tool exposed; only predefined, strictly validated domain operations are permitted.
- **Reliable Lifecycle Management:** Sequential FIFO execution queue, unique UUIDv4 command tracking, result verification, and structured error responses.

---

## Installation

### Prerequisites
- [Node.js](https://nodejs.org/) >= 18 (Node 22 or 26 recommended)
- Adobe After Effects 2026, 2025, or 2024 (Windows 11 / 10)

### Clone & Build

```bash
git clone https://github.com/Narendhiran17/After-Effects-MCP.git
cd After-Effects-MCP
npm install
npm run build
```

---

## Configuration

Copy `.env.example` to `.env`:

```bash
cp .env.example .env
```

| Environment Variable | Description | Default |
| :--- | :--- | :--- |
| `AE_EXECUTABLE_PATH` | Full path to `AfterFX.exe` | Auto-detected from standard directories |
| `AE_COMMAND_TIMEOUT_MS` | ExtendScript execution timeout in milliseconds | `30000` |
| `AE_MOCK_MODE` | Set to `true` to run simulation without launching AE | `false` |
| `AE_ALLOWED_STORAGE_ROOT` | Permitted root directory for asset imports and exports | `./storage` |
| `AE_LOG_LEVEL` | Logging verbosity (`debug`, `info`, `warn`, `error`) | `info` |

---

## Connecting with AI Clients

Add the server to your MCP client configuration file (e.g. `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "after-effects": {
      "command": "node",
      "args": ["<PATH_TO_REPO>/dist/index.js"],
      "env": {
        "AE_MOCK_MODE": "false"
      }
    }
  }
}
```

---

## Available Tools (34 Tools)

### 1. System & Diagnostics
- `ae.system.status` - Check After Effects installation, version, and bridge availability.

### 2. Project Management
- `ae.project.create` - Create a new project.
- `ae.project.open` - Open an existing `.aep` project file.
- `ae.project.save` - Save current project (or Save As).
- `ae.project.close` - Close project (high-risk; requires confirmation approval).
- `ae.project.inspect` - Inspect project hierarchy, active compositions, and total items.
- `ae.project.validate` - Validate project integrity and detect missing footage.

### 3. Composition Management
- `ae.composition.create` - Create composition with custom dimensions, framerate, and duration.
- `ae.composition.update` - Update dimensions, duration, or framerate of existing composition.
- `ae.composition.delete` - Delete composition (high-risk; requires approval).
- `ae.composition.inspect` - Inspect composition properties and list all layers.

### 4. Layer Management
- `ae.layer.create` - Create solid, text, shape, camera, light, or null layers.
- `ae.layer.delete` - Delete layer from composition.
- `ae.layer.duplicate` - Duplicate layer.
- `ae.layer.transform` - Set/animate position, scale, rotation, opacity, and anchor point.
- `ae.layer.inspect` - Inspect layer properties, transform coordinates, and timing.

### 5. Text & Typography
- `ae.text.create` - Create text layer with custom typography formatting and position.
- `ae.text.update` - Update text content.
- `ae.text.style` - Set font, size, fill/stroke colors, tracking, and alignment.

### 6. Animation & Keyframes
- `ae.animation.keyframe.create` - Create a keyframe on any transform/effect property at a timestamp.
- `ae.animation.keyframe.update` - Modify keyframe time or value.
- `ae.animation.easing.set` - Set temporal easing (speed and influence) and interpolation.

### 7. Effects & Presets
- `ae.effects.apply` - Apply an effect by match name or display name.
- `ae.effects.configure` - Set property parameters of an applied effect.

### 8. Assets & Media
- `ae.assets.import` - Import video, image, or audio footage.
- `ae.assets.inspect` - List and inspect imported footage items.

### 9. Audio Operations
- `ae.audio.add` - Add audio track to timeline.
- `ae.audio.volume.set` - Set audio levels in decibels (dB).
- `ae.audio.fade.create` - Create audio fade-in or fade-out.

### 10. Rendering & Output
- `ae.render.queue` - Add composition to the render queue with output path and template.
- `ae.render.start` - Start background rendering.
- `ae.render.status` - Check status of render queue jobs.
- `ae.render.cancel` - Pause or cancel active render.

### 11. Timeline
- `ae.timeline.inspect` - Inspect composition timeline structure, layer timing, and parent hierarchy.

---

## Resources & Prompts

### Resources
- `ae://system/status` - Current system status and bridge health.
- `ae://system/version` - Target After Effects version.
- `ae://project/current` - Active project metadata.
- `ae://project/compositions` - Compositions in current project.
- `ae://project/assets` - Imported footage items.
- `ae://composition/{id}` - Detailed composition settings.
- `ae://composition/{id}/layers` - Layers within a composition.
- `ae://render/jobs` - Active and queued render jobs.

### Prompts
- `create-motion-graphics-intro` - Create a motion graphics introduction sequence.
- `create-animated-title` - Create an animated title card with easing.
- `build-social-media-composition` - Create 9:16 vertical composition for social media.
- `create-logo-animation` - Create a logo reveal animation sequence.
- `prepare-render` - Validate and queue a composition for rendering.
- `diagnose-project` - Diagnose active project structure and missing files.

---

## Testing

Run unit, integration, and bridge tests with Vitest:

```bash
npm test
```

Build TypeScript to `dist/`:

```bash
npm run build
```

---

## Documentation

- [Tools Reference](docs/tools-reference.md)
- [Bridge Protocol Specification](docs/bridge-protocol.md)
- [Security Architecture](docs/security.md)
- [Technical Architecture Baseline](ARCHITECTURE.md)

---

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.