ae-mcp

영어 | 简体中文

한 줄 설정 프롬프트 — Claude Code 또는 다른 AI 에이전트에 붙여넣으세요:

Install the ae-mcp ZXP and the native plug-in for my platform from the v0.10.3
release, open Window > Extensions
> ae-mcp in After Effects, then connect Claude Code with `claude mcp add
--transport http ae http://127.0.0.1:11488/mcp`; for Claude Desktop, configure
the extension's `host/stdio-shim.js` with the system Node executable and ask me
to start a new client session before testing `ae_status`.

ae-mcp는 로컬 MCP 엔드포인트를 통해 After Effects CEP 패널을 AI 클라이언트에 연결합니다. 패널은 http://127.0.0.1:11488/mcp에서 서비스를 호스팅하며, 호스트는 Express를 사용하는 Node 프로세스이고, After Effects 상태는 ExtendScript와 동결된 네이티브 AEGP 플레인을 통해 접근합니다.

설치 및 첫 실행

1. 서명된 ZXP를 After Effects에 설치하세요.

2. 호스트용으로 선택된 After Effects 플러그인 옆에 일치하는 네이티브 플러그인을 설치하세요 — Windows에서는 .aex, macOS에서는 AeMcpNative.plugin 번들입니다. 동일 릴리스의 버전 쌍을 유지하세요. ZXP에는 플랫폼 바이너리가 포함되어 있지 않으며 두 시스템 모두에 설치됩니다. 이 네이티브 플러그인만 플랫폼별로 빌드되며, ae_nativeExec가 이를 필요로 하는 유일한 도구입니다. 설치 문서에 플랫폼별 정확한 대상 위치가 있으며, macOS 번들은 After Effects가 로드하기 전에 다운로드 격리(quarantine)를 추가로 해제해야 합니다.

3. After Effects를 시작하고 Window > Extensions > ae-mcp를 여세요. 외부 클라이언트가 MCP를 사용하는 동안 패널을 열어 두세요.

4. 아래의 지원되는 두 가지 외부 연결 형식 중 하나를 구성하세요.

패널 자체가 MCP 서비스입니다. 별도의 저장소 서버가 필요하지 않습니다. 기본 엔드포인트가 루프백이므로 외부 클라이언트는 After Effects와 동일한 머신에서 실행되어야 합니다.

Related MCP server: After Effects MCP

클라이언트 연결

Claude Code는 URL 전송을 사용합니다:

claude mcp add --transport http ae http://127.0.0.1:11488/mcp

Claude Desktop은 설치된 확장 디렉터리에 접근할 필요 없이 시스템 Node 설치를 통해 게시된 커넥터를 사용할 수 있습니다. 이 npx -y ae-mcp-jkdg 형식은 동일한 의존성 없는 host/stdio-shim.js를 래핑합니다:

{
  "mcpServers": {
    "ae": {
      "command": "npx",
      "args": ["-y", "ae-mcp-jkdg"]
    }
  }
}

또는 Claude Desktop은 설치된 확장에 포함된 의존성 없는 stdio 셔임(shim)을 실행할 수 있습니다. command를 시스템 Node 실행 파일로 설정하고 args를 확장 디렉터리의 host/stdio-shim.js로 지정하세요:

{
  "mcpServers": {
    "ae": {
      "command": "node",
      "args": ["<installed-extension>/host/stdio-shim.js"],
      "env": {
        "AE_MCP_HTTP_URL": "http://127.0.0.1:11488/mcp"
      }
    }
  }
}

따라서 Claude Desktop에는 시스템 Node 설치가 필요합니다. 셔임은 하나의 stdio 요청 큐를 유지하고 MCP 응답을 패널 호스트로 전달합니다.

패널 기능

• 유지 관리되는 ExtendScript 작업을 위한 ae_exec.

• 디스패치된 ae_exec 실패를 반환된 id로 재시도하기 위한 ae_execRecover.

• 동결된 네이티브 AEGP 프리미티브를 위한 ae_nativeExec.

• ae_previewFrame, ae_validateExpressions, 구조화된 ae_read 및 체크포인트.

• 번들된 스킬과 로컬 JSX 도구 라이브러리.

• 승인 모드, 활동 기록, 진단 및 로그 내보내기.

• 로컬 CLI 로그인을 사용할 수 있을 때 내장된 Claude, Codex 및 OpenCode 채널.

공개 MCP 도구는 CEP 호스트에서 제공됩니다. 쓰기 작업 후에는 독립적인 읽기 확인(readback)이 뒤따라야 하며, 부작용 가능성이 있는 실패는 재시도 전에 조정되어야 하고, 실행 취소(Undo)는 별도로 실행 및 검증되어야 합니다.

개발

두 개의 Node 워크스페이스를 설치하고 패널을 빌드하세요:

(cd plugin/host && npm ci)
(cd plugin/panel && npm ci && npm run build)

로컬 CEP 배포의 경우 호스트와 패널이 빌드된 후 플랫폼별 스크립트를 사용하세요:

.\scripts\install-plugin-dev.ps1

./scripts/install-plugin-dev-macos.sh

Adobe After Effects C/C++ 플러그인 SDK는 개발자가 제공하는 입력이며 이 저장소 외부에 유지되어야 합니다. 네이티브 플러그인을 빌드하기 전에 이를 확인하세요:

node scripts/package/ae-sdk-input.mjs verify-input --platform macos-arm64

동결된 네이티브 플레인의 경우 저장소 외부의 새 디렉터리에 빌드하세요. 설치 프로그램은 native-plugin-dev-v1 아래에 트랜잭션 상태를 유지합니다. 결과물을 설치하는 경우 반환된 트랜잭션 ID를 보관하세요:

AE_SDK_ARCHIVE=/absolute/path/AfterEffectsSDK.zip
AE_SDK_ROOT=/absolute/path/AfterEffectsSDK
BUILD_DIR=/private/tmp/ae-mcp-native-dev
TRANSACTION_ID="paste-the-transaction-id-here"
node native/ae-plugin/build-macos.mjs \
  --sdk-archive "$AE_SDK_ARCHIVE" \
  --sdk-root "$AE_SDK_ROOT" \
  --output "$BUILD_DIR"
# The install state root is native-plugin-dev-v1.
node native/ae-plugin/install-dev-macos.mjs install --artifact-dir "$BUILD_DIR"
node native/ae-plugin/install-dev-macos.mjs rollback \
  --transaction "$TRANSACTION_ID"

네이티브 플레인은 동결되어 있습니다. 생성된 AEGP 프로토콜 파일은 체크인되어 있으며, 기능 패키지 코드 생성 파이프라인은 일반 개발 프로세스에 포함되지 않습니다.

테스트 및 패키징

로컬에서 집중된 Node 계약(contract) 테스트를 실행하세요:

node --test scripts/package/test/verify-windows-zxp-stage.test.mjs
node --test scripts/package/test/zxp-payload-audit.test.mjs

Windows ZXP 스테이징 명령은 패널, 호스트, JSX, 공유 모듈, 아이콘 및 생성된 호스트 에셋만 복사합니다. 호스트의 정확한 Express 4.22.2 종속성을 검증하고 ZXP를 한 번 서명합니다:

.\scripts\package-zxp.ps1 -SkipSigning

서명된 ZXP에는 명시적으로 처리된 .aex 아티팩트 외에 중첩된 네이티브 바이너리가 포함되어서는 안 되며, 20MB 미만으로 유지되어야 합니다.

유지 관리되는 운영 세부 정보는 설치, 참조 및 릴리스 문서를 참조하세요.

라이선스

ae-mcp는 MIT 라이선스로 배포됩니다. LICENSE를 참조하세요. Adobe의 CSInterface.js에는 업스트림 라이선스 고지가 유지됩니다.