AE Motion

Servidor MCP de AE Motion

Un servidor MCP que permite a Claude (o cualquier cliente MCP) construir, animar, previsualizar y renderizar gráficos en movimiento en un proyecto vivo de Adobe After Effects.

Pide "un tercio inferior de 5 segundos con una entrada deslizante suavizada", y el modelo crea la composición, añade capas, establece fotogramas clave, comprueba un fotograma de previsualización y lanza un render, todo en el proyecto que tengas abierto.

https://github.com/user-attachments/assets/4734d955-5c97-4644-a387-f05d4dc0e2f6

https://github.com/user-attachments/assets/c05af0f1-3f7e-4a31-84ef-cbc0fb87006d

Vídeo completo: Ver aquí

MCP client --stdio--> MCP server (Node) --HTTP 127.0.0.1 + token--> CEP panel in AE --> ExtendScript

Contenido

• Requisitos
• Instalación
• Verificar que funciona
• Qué puede hacer
• Configuración
• Seguridad
• Solución de problemas
• Actualizaciones
• Actualizar y desinstalar
• Documentación

Requisitos

• After Effects 2022 (22.0) o posterior, en macOS o Windows
• Node.js 22.18 o posterior (la compilación y las pruebas ejecutan TypeScript directamente mediante la eliminación de tipos de Node)
• Un cliente MCP como Claude Code o Claude Desktop

Instalación

1. Obtén el código y ejecuta el instalador

git clone https://github.com/dha-aa/ae-motion.git
cd ae-motion

macOS:

bash scripts/install.sh

Windows (PowerShell):

./scripts/install.ps1

El instalador:

1. Ejecuta npm install && npm run build, que produce el servidor (dist/) y el script host del panel (panel/host/host.jsx).
2. Copia panel/ en la carpeta de extensiones CEP:
   • macOS: ~/Library/Application Support/Adobe/CEP/extensions/com.aemotion.mcp
   • Windows: %APPDATA%\Adobe\CEP\extensions\com.aemotion.mcp
3. Habilita los paneles CEP sin firmar (PlayerDebugMode, CSXS 9 a 12). Este ajuste por usuario es necesario para cualquier panel que no esté firmado por Adobe.

¿Prefieres instalar manualmente?

1. En la carpeta del repositorio, ejecuta npm install && npm run build.
2. Copia el contenido de panel/ en la carpeta de extensiones anterior, en una carpeta llamada com.aemotion.mcp.
3. Habilita los paneles sin firmar.
   • macOS: for v in 9 10 11 12; do defaults write com.adobe.CSXS.$v PlayerDebugMode 1; done
   • Windows: para cada uno de 9 a 12, reg add "HKCU\Software\Adobe\CSXS.<v>" /v PlayerDebugMode /t REG_SZ /d 1 /f

2. Permite scripts en After Effects

Abre las preferencias, ve a Scripting & Expressions y habilita Allow Scripts to Write Files and Access Network.

• macOS: After Effects > Settings
• Windows: Edit > Preferences

3. Abre el panel

Reinicia After Effects y luego abre Window > Extensions > AE Motion MCP y mantenlo abierto. Acoplarlo en un espacio de trabajo hace que se cargue al iniciar.

El panel inicia un pequeño servidor en 127.0.0.1 (puerto 47670, o el siguiente puerto libre hasta 47690) y escribe su puerto y un token aleatorio en ~/.ae-motion-mcp/bridge.json. El servidor MCP lee ese archivo para encontrarlo. Si el panel está cerrado, cada herramienta devuelve BRIDGE_DOWN.

El panel también muestra un medidor de tokens: los tokens estimados que ae-motion ha añadido al contexto del modelo en esta sesión (resultados de herramientas e imágenes de previsualización), y el tamaño de sus definiciones de herramientas por solicitud. Solo cuenta lo que envía ae-motion; tus mensajes y las respuestas del modelo están aparte (tu cliente muestra el recuento completo).

4. Registra el servidor con tu cliente

Usa la ruta absoluta a dist/index.js.

Claude Code

claude mcp add ae-motion -- node /absolute/path/to/ae-motion/dist/index.js

Claude Desktop: añade esto a claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\) y reinicia la aplicación.

{
  "mcpServers": {
    "ae-motion": {
      "command": "node",
      "args": ["/absolute/path/to/ae-motion/dist/index.js"],
      "env": { "AE_MCP_TOOLSETS": "core" }
    }
  }
}

AE_MCP_TOOLSETS: core inicia Claude Desktop solo con las herramientas principales (aproximadamente 7.5k tokens de definiciones de herramientas en lugar de 16k en cada mensaje); el modelo añade 3D, línea de tiempo, máscaras, diseño o scripting con load_tools cuando las necesita. Déjalo fuera para cargar todo. Claude Code no lo necesita: carga las herramientas MCP solo cuando se usan.

Otros clientes: cualquier cliente que pueda lanzar un servidor MCP stdio funciona con node /absolute/path/to/ae-motion/dist/index.js.

Para establecer variables de entorno, añade un objeto env junto a args en el JSON anterior, o pasa --env KEY=value a claude mcp add (antes del nombre del servidor).

Verificar que funciona

1. La línea de estado del panel muestra 127.0.0.1:<port>, y ~/.ae-motion-mcp/bridge.json existe.
2. En tu cliente, pregunta: "obtén la información del proyecto". Deberías obtener las composiciones, el material de archivo y la versión de After Effects.
3. Luego prueba algo visible: "crea una composición de 1920x1080 a 30 fps, 5 segundos, con un fondo sólido blanco, y muéstrame el fotograma 0".

Si una llamada falla, el error incluye un código y una pista. Consulta Solución de problemas.

Qué puede hacer

78 herramientas en trece grupos. La referencia completa, con notas de comportamiento, está en docs/tools.md.

Grupo	Herramientas
Inspección	get_project, get_comp, get_layer, list_properties, get_keyframes, find_effects
Proyecto	open_project, save_project, create_comp, set_comp, import_footage, set_item, delete_item
Capas	add_layer, set_layer, link_layers, replace_source, delete_layer, duplicate_layer, reorder_layer, precompose
Línea de tiempo	split_layer, delete_range, insert_time, shift_layers, sequence_layers, align_to_markers, trim_comp, set_playhead, add_marker, update_marker, list_markers, delete_marker
Máscaras y mates	add_mask, set_track_matte
Diseño	align_layers, set_anchor, add_shape, add_layer_style, text_to_shapes
Animar	set_property, set_keyframes, edit_keyframes, copy_animation, set_expression, add_property, apply_effect, edit_effect, apply_preset, set_text, get_text, find_fonts, stagger, add_shape_modifier
Movimiento	animate (movimientos nombrados con resortes y rebotes), text_reveal, transition (cortinilla, barras, iris), review_motion (un crítico de movimiento)
3D y cámara	get_camera, set_camera, camera_move, camera_shake, camera_rig, set_3d, set_light, set_3d_view
Previsualización y render	preview_frame, render_start, render_status, render_cancel
Vía de escape	run_jsx (deshabilitada a menos que AE_MCP_ALLOW_JSX=1)
Audio	beat_markers, audio_react, find_sound_cues, add_sfx, duck_music
Servidor	check_for_updates, batch (muchos pasos en una sola llamada), load_tools (solo con AE_MCP_TOOLSETS)

También: recursos ae://project y ae://selection, y el prompt motion-guide (convenciones y un bucle de construcción recomendado).

Convenciones: tiempo en segundos, tamaños en píxeles, colores [r,g,b] flotantes de 0 a 1, escala en porcentaje. Las composiciones y capas se abordan por los IDs numéricos que devuelven las herramientas; las propiedades por alias (position, scale, rotation, opacity, anchor) o una matriz de nombres de coincidencia (list_properties los descubre). Cada llamada mutadora es un paso de deshacer en After Effects.

Ejemplos de prompts: "orbita la cámara 120 grados alrededor del producto durante 4 segundos", "corta de 3s a 5s de cada capa y cierra el hueco", "alinea estas cinco capas una tras otra con una superposición de 10 fotogramas", "haz estas tarjetas 3D, gíralas 25 grados y añade una luz puntual con sombras", "centra el título y dale una sombra suave", "espacia estos iconos uniformemente a lo largo de la parte inferior".

Configuración

Todos los ajustes son variables de entorno en el proceso del servidor MCP. La única excepción es AE_MCP_BRIDGE_FILE, que también debe establecerse para el entorno del panel si lo cambias.

Variable	Efecto
AE_MCP_ALLOWED_DIRS	Carpetas (separadas por el delimitador de ruta del sistema operativo, : o ;) desde las que las herramientas pueden leer y escribir. Predeterminado: tu carpeta de inicio. La carpeta temporal siempre está permitida.
AE_MCP_ALLOW_JSX	Establece 1 para habilitar run_jsx.
AE_MCP_TOOLSETS	Carga solo algunos grupos de herramientas, para enviar al modelo menos definiciones de herramientas (solicitudes más baratas): una lista separada por comas de project, layers, timeline, masks, animate, motion, scene3d, design, output, audio, scripting o core (= proyecto, capas, animar, movimiento, salida: aproximadamente 7.5k tokens de definiciones en lugar de 16k). inspect, check_for_updates y batch están siempre activos, y load_tools añade los otros grupos durante una sesión (se le dice al cliente que actualice su lista de herramientas; las nuevas herramientas también pasan por batch). Predeterminado: todos.
AE_AERENDER	Ruta completa a aerender si falla la detección automática.
AE_MCP_BRIDGE_FILE	Sobrescribe el archivo puente (predeterminado ~/.ae-motion-mcp/bridge.json).
AE_MCP_UPDATE_CHECK	Establece 0 para desactivar la comprobación diaria de nuevas versiones (consulta Actualizaciones).

Seguridad

• El panel solo escucha en 127.0.0.1, y cada solicitud necesita el token aleatorio almacenado en el archivo puente, que se crea legible solo por tu usuario.
• Las rutas de archivo pasadas a las herramientas (import_footage, apply_preset, save_project, salida de render) deben estar dentro de AE_MCP_ALLOWED_DIRS.
• run_jsx puede ejecutar cualquier cosa que After Effects pueda, por lo que está desactivado a menos que optes por activarlo.
• Instalar el panel activa PlayerDebugMode para CEP, lo que permite a este usuario cargar cualquier panel sin firmar. Desactívalo si desinstalas (consulta abajo).

Solución de problemas

Síntoma	Causa y solución
BRIDGE_DOWN: Archivo puente no encontrado	El panel no está abierto. Abre Window > Extensions > AE Motion MCP y mantenlo abierto.
BRIDGE_DOWN: rechazó el token (archivo puente obsoleto)	After Effects se reinició o el panel se recargó. Cierra y vuelve a abrir el panel.
BRIDGE_DOWN: No se puede alcanzar el panel de After Effects	After Effects no está ejecutándose, o el panel está cerrado. Comprueba la línea de estado en el panel.
El panel no está en el menú Window > Extensions	Vuelve a ejecutar el instalador, asegúrate de que PlayerDebugMode esté establecido para tu versión de CSXS y luego reinicia After Effects por completo.
El estado del panel muestra "Cannot write bridge file"	~/.ae-motion-mcp/ no puede crearse o escribirse por tu usuario. Corrige los permisos de la carpeta, o apunta AE_MCP_BRIDGE_FILE a una ubicación escribible (tanto para el panel como para el servidor).
preview_frame o import_footage fallan con un error de permiso de scripting	Habilita Allow Scripts to Write Files and Access Network en After Effects (consulta Instalación).
FORBIDDEN: ruta fuera de las carpetas permitidas	Añade la carpeta a AE_MCP_ALLOWED_DIRS.
FORBIDDEN: run_jsx está deshabilitado	Establece AE_MCP_ALLOW_JSX=1 en el entorno del servidor.
TIMEOUT	El mensaje dice qué ocurrió: aún en ejecución (termina solo: inspecciona el estado antes de reintentar), o se descartó antes de comenzar porque After Effects estaba ocupado con otro comando (seguro reintentar). Un diálogo modal abierto en After Effects bloquea los comandos.
AE_ERROR: aerender no encontrado	Establece AE_AERENDER a la ruta completa del ejecutable aerender.
BAD_ARGS: El proyecto nunca se ha guardado	Guarda el proyecto una vez (o llama a save_project con una ruta) y luego llama a render_start de nuevo.
EXISTS en render_start	El archivo de salida existe. Pasa overwrite: true o elige otra ruta.
UNSUPPORTED en preview_frame	Tu versión de After Effects no tiene saveFrameToPng. Actualiza After Effects.
AE_ERROR con la pista "ExtendScript line N"	N es una línea del panel/host/host.jsx instalado; los banners // ---- host/<file> ---- allí muestran de qué archivo fuente proviene. Por favor, abre un issue.
Unknown file extension ".ts" durante la instalación o npm test	Tu Node.js es anterior a 22.18, que no puede ejecutar archivos .ts directamente. Actualiza Node.js (node --version para comprobar).
Los cambios en el servidor no se muestran	Ejecuta npm run build y luego reinicia el servidor MCP desde tu cliente. Los cambios en host/ o panel/ también necesitan que se vuelva a ejecutar el instalador y se reabra el panel.
Los registros del panel están en ~/Library/Logs/CSXS/ en macOS y %TEMP% (csxs*.log) en Windows.

Actualizaciones

Puedes enterarte de nuevas versiones en tres lugares:

• El panel de After Effects muestra la versión instalada y, cuando existe una versión más reciente, una línea como v2.1.0 available con un botón Update to v2.1.0.
• Tu cliente de IA: get_project (normalmente la primera llamada) incluye una nota update con la nueva versión y el comando a ejecutar, para que el modelo pueda informarte. También puedes preguntar "check for updates" (check_for_updates).
• GitHub: los lanzamientos son etiquetas git vX.Y.Z; lo que cambió está en CHANGELOG.md.

Cómo funciona la comprobación: el servidor MCP pregunta a GitHub por las etiquetas de versión del repositorio como máximo una vez al día, en segundo plano, con un tiempo de espera corto, y guarda la respuesta en ~/.ae-motion-mcp/update.json (el panel solo lee ese archivo). No envía nada más que una solicitud anónima normal, y una comprobación fallida nunca afecta a una herramienta. Establece AE_MCP_UPDATE_CHECK=0 para desactivarlo.

Actualizar y desinstalar

Actualizar desde el panel: haz clic en Update to vX.Y.Z (o Reinstall) en el panel de AE Motion MCP, y luego haz clic de nuevo para confirmar. Ejecuta scripts/update.ts en tu carpeta ae-motion, que descarga la etiqueta de lanzamiento más reciente (nunca trabajo sin publicar en main) y ejecuta el instalador, muestra la salida y reinicia el panel con la nueva versión; luego reinicia tu cliente de IA para que use el nuevo servidor. La descarga se deja en esa etiqueta (git switch main vuelve atrás). El panel encuentra la carpeta y tu git / node / npm a través de install.json, que el instalador escribe, por lo que un panel instalado antes de que existiera este botón necesita una actualización manual primero. Si tienes cambios locales, se detiene y lo indica: haz commit o stash de ellos, o actualiza manualmente.

Actualizar manualmente: en la carpeta del repositorio, node scripts/update.ts (el lanzamiento más reciente, luego el instalador). O git pull para la última main, y luego ejecuta el instalador de nuevo (bash scripts/install.sh, o ./scripts/install.ps1 en Windows; reconstruye y reemplaza el panel instalado). Vuelve a abrir el panel de AE Motion MCP (o reinicia After Effects) y reinicia el servidor MCP desde tu cliente. La línea de Versión del panel muestra la nueva versión.

Desinstalar:

1. Elimina el servidor de tu cliente (claude mcp remove ae-motion, o borra la entrada de la configuración de Claude Desktop).
2. Elimina la carpeta del panel instalado (consulta Installation).
3. Elimina ~/.ae-motion-mcp/.
4. Opcional: vuelve a desactivar los paneles sin firmar.
   • macOS: for v in 9 10 11 12; do defaults delete com.adobe.CSXS.$v PlayerDebugMode; done
   • Windows: elimina el valor PlayerDebugMode bajo HKCU\Software\Adobe\CSXS.9 para CSXS.12.

Documentación

• docs/tools.md: cada herramienta, los modelos de línea de tiempo y cámara, y notas de comportamiento
• docs/architecture.md: cómo encajan las piezas, el protocolo de cable, la estructura del repositorio
• CONTRIBUTING.md: las reglas para cambiar ae-motion y la lista de verificación previa a la fusión
• docs/development.md: compilación, pruebas, agregar una herramienta, peculiaridades de After Effects, estado de verificación
• docs/future.md: cambios que vienen desde fuera de ae-motion, como Adobe reemplazando CEP por UXP

Licencia

MIT