AE Motion

Servidor MCP AE Motion

Um servidor MCP que permite ao Claude (ou qualquer cliente MCP) criar, animar, visualizar e renderizar motion graphics em um projeto ativo do Adobe After Effects.

Peça por "um lower third de 5 segundos com entrada suave", e o modelo cria a composição, adiciona camadas, define keyframes, verifica um frame de pré-visualização e inicia uma renderização, tudo no projeto que você tem aberto.

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: Assista aqui

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

Conteúdo

• Requisitos
• Instalação
• Verifique se funciona
• O que ele pode fazer
• Configuração
• Segurança
• Solução de problemas
• Atualizações
• Atualizar e desinstalar
• Documentação

Requisitos

• After Effects 2022 (22.0) ou posterior, no macOS ou Windows
• Node.js 22.18 ou posterior (o build e os testes executam TypeScript diretamente através do type stripping do Node)
• Um cliente MCP como Claude Code ou Claude Desktop

Instalação

1. Obtenha o código e execute o instalador

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

macOS:

bash scripts/install.sh

Windows (PowerShell):

./scripts/install.ps1

O instalador:

1. Executa npm install && npm run build, que produz o servidor (dist/) e o script host do painel (panel/host/host.jsx).
2. Copia panel/ para a pasta de extensões CEP:
   • macOS: ~/Library/Application Support/Adobe/CEP/extensions/com.aemotion.mcp
   • Windows: %APPDATA%\Adobe\CEP\extensions\com.aemotion.mcp
3. Habilita painéis CEP não assinados (PlayerDebugMode, CSXS 9 a 12). Essa configuração por usuário é necessária para qualquer painel que não seja assinado pela Adobe.

Prefere instalar manualmente?

1. Na pasta do repositório, execute npm install && npm run build.
2. Copie o conteúdo de panel/ para a pasta de extensões acima, em uma pasta chamada com.aemotion.mcp.
3. Habilite painéis não assinados.
   • macOS: for v in 9 10 11 12; do defaults write com.adobe.CSXS.$v PlayerDebugMode 1; done
   • Windows: para cada um de 9 a 12, reg add "HKCU\Software\Adobe\CSXS.<v>" /v PlayerDebugMode /t REG_SZ /d 1 /f

2. Permita scripts no After Effects

Abra as preferências, vá em Scripting & Expressions e habilite Allow Scripts to Write Files and Access Network.

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

3. Abra o painel

Reinicie o After Effects e abra Window > Extensions > AE Motion MCP, mantendo-o aberto. Encaixá-lo em um workspace faz com que ele carregue na inicialização.

O painel inicia um pequeno servidor em 127.0.0.1 (porta 47670, ou a próxima porta livre até 47690) e grava sua porta e um token aleatório em ~/.ae-motion-mcp/bridge.json. O servidor MCP lê esse arquivo para encontrá-lo. Se o painel estiver fechado, toda ferramenta retorna BRIDGE_DOWN.

O painel também mostra um medidor de tokens: os tokens estimados que o ae-motion adicionou ao contexto do modelo nesta sessão (resultados de ferramentas e imagens de pré-visualização), e o tamanho de suas definições de ferramentas por requisição. Ele conta apenas o que o ae-motion envia; suas mensagens e as respostas do modelo ficam por cima (seu cliente mostra a contagem completa).

4. Registre o servidor no seu cliente

Use o caminho absoluto para dist/index.js.

Claude Code

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

Claude Desktop: adicione isso a claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\) e reinicie o aplicativo.

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

AE_MCP_TOOLSETS: core inicia o Claude Desktop apenas com as ferramentas principais (cerca de 7,5 mil tokens de definições de ferramentas em vez de 16 mil em cada mensagem); o modelo adiciona 3D, timeline, máscaras, design ou scripts com load_tools quando precisar. Deixe de fora para carregar tudo. O Claude Code não precisa disso: ele carrega ferramentas MCP apenas quando são usadas.

Outros clientes: qualquer cliente que possa iniciar um servidor MCP stdio funciona com node /absolute/path/to/ae-motion/dist/index.js.

Para definir variáveis de ambiente, adicione um objeto env ao lado de args no JSON acima, ou passe --env KEY=value para claude mcp add (antes do nome do servidor).

Verifique se funciona

1. A linha de status do painel mostra 127.0.0.1:<port>, e ~/.ae-motion-mcp/bridge.json existe.
2. No seu cliente, pergunte: "obtenha as informações do projeto". Você deve receber as composições, as filmagens e a versão do After Effects.
3. Depois tente algo visível: "crie uma composição 1920x1080 a 30 fps, 5 segundos, com um fundo sólido branco, e me mostre o frame 0".

Se uma chamada falhar, o erro inclui um código e uma dica. Veja Solução de problemas.

O que ele pode fazer

77 ferramentas em treze grupos. A referência completa, com notas de comportamento, está em docs/tools.md.

Grupo	Ferramentas
Inspeção	get_project, get_comp, get_layer, list_properties, get_keyframes, find_effects
Projeto	open_project, save_project, create_comp, set_comp, import_footage, delete_item
Camadas	add_layer, set_layer, link_layers, replace_source, delete_layer, duplicate_layer, reorder_layer, precompose
Timeline	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 e mattes	add_mask, set_track_matte
Design	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
Movimento	animate (movimentos nomeados com molas e quiques), text_reveal, transition (wipe, barras, íris), review_motion (um crítico de movimento)
3D e câmera	get_camera, set_camera, camera_move, camera_shake, camera_rig, set_3d, set_light, set_3d_view
Pré-visualização e renderização	preview_frame, render_start, render_status, render_cancel
Saída de emergência	run_jsx (desabilitado a menos que AE_MCP_ALLOW_JSX=1)
Áudio	beat_markers, audio_react, find_sound_cues, add_sfx, duck_music
Servidor	check_for_updates, batch (muitas etapas em uma chamada), load_tools (apenas com AE_MCP_TOOLSETS)

Também: recursos ae://project e ae://selection, e o prompt motion-guide (convenções e um loop de construção recomendado).

Convenções: tempo em segundos, tamanhos em pixels, cores [r,g,b] floats de 0 a 1, escala em porcentagem. Composições e camadas são endereçadas pelos IDs numéricos que as ferramentas retornam; propriedades por alias (position, scale, rotation, opacity, anchor) ou um array de match names (list_properties os descobre). Toda chamada de mutação é uma etapa de desfazer no After Effects.

Exemplos de prompts: "orbite a câmera 120 graus ao redor do produto em 4 segundos", "corte 3s a 5s de cada camada e feche a lacuna", "alinhe essas cinco camadas uma após a outra com uma sobreposição de 10 frames", "torne esses cards 3D, gire-os 25 graus e adicione uma luz de spot com sombras", "centralize o título e dê a ele uma sombra projetada suave", "distribua esses ícones uniformemente na parte inferior".

Configuração

Todas as configurações são variáveis de ambiente no processo do servidor MCP. A única exceção é AE_MCP_BRIDGE_FILE, que também deve ser definida para o ambiente do painel se você a alterar.

Variável	Efeito
AE_MCP_ALLOWED_DIRS	Pastas (separadas pelo delimitador de caminho do SO, : ou ;) das quais as ferramentas podem ler e para as quais podem gravar. Padrão: sua pasta pessoal. A pasta temporária é sempre permitida.
AE_MCP_ALLOW_JSX	Defina como 1 para habilitar run_jsx.
AE_MCP_TOOLSETS	Carregue apenas alguns grupos de ferramentas, para enviar ao modelo menos definições de ferramentas (requisições mais baratas): uma lista separada por vírgulas de project, layers, timeline, masks, animate, motion, scene3d, design, output, audio, scripting ou core (= projeto, camadas, animar, movimento, saída: cerca de 7,5 mil tokens de definições em vez de 16 mil). inspect, check_for_updates e batch estão sempre ativos, e load_tools adiciona os outros grupos durante uma sessão (o cliente é informado para atualizar sua lista de ferramentas; as novas ferramentas também passam por batch). Padrão: todos.
AE_AERENDER	Caminho completo para aerender se a detecção automática falhar.
AE_MCP_BRIDGE_FILE	Substitua o arquivo de ponte (padrão ~/.ae-motion-mcp/bridge.json).
AE_MCP_UPDATE_CHECK	Defina como 0 para desativar a verificação diária de novos lançamentos (veja Atualizações).

Segurança

• O painel escuta apenas em 127.0.0.1, e toda requisição precisa do token aleatório armazenado no arquivo de ponte, que é criado legível apenas pelo seu usuário.
• Caminhos de arquivo passados para ferramentas (import_footage, apply_preset, save_project, saída de renderização) devem estar dentro de AE_MCP_ALLOWED_DIRS.
• run_jsx pode executar qualquer coisa que o After Effects possa, então fica desligado a menos que você opte por ativá-lo.
• Instalar o painel ativa PlayerDebugMode para CEP, o que permite que este usuário carregue qualquer painel não assinado. Desative-o novamente se desinstalar (veja abaixo).

Solução de problemas

Sintoma	Causa e correção
BRIDGE_DOWN: Arquivo de ponte não encontrado	O painel não está aberto. Abra Window > Extensions > AE Motion MCP e mantenha-o aberto.
BRIDGE_DOWN: rejeitou o token (arquivo de ponte desatualizado)	O After Effects foi reiniciado ou o painel foi recarregado. Feche e reabra o painel.
BRIDGE_DOWN: Não é possível alcançar o painel do After Effects	O After Effects não está em execução, ou o painel está fechado. Verifique a linha de status no painel.
O painel não está no menu Window > Extensions	Execute o instalador novamente, certifique-se de que PlayerDebugMode está definido para sua versão CSXS e reinicie completamente o After Effects.
O status do painel mostra "Cannot write bridge file"	~/.ae-motion-mcp/ não pode ser criado ou gravado pelo seu usuário. Corrija as permissões da pasta, ou aponte AE_MCP_BRIDGE_FILE para um local gravável (tanto para o painel quanto para o servidor).
preview_frame ou import_footage falham com um erro de permissão de script	Habilite Allow Scripts to Write Files and Access Network no After Effects (veja Instalação).
FORBIDDEN: caminho fora das pastas permitidas	Adicione a pasta a AE_MCP_ALLOWED_DIRS.
FORBIDDEN: run_jsx está desabilitado	Defina AE_MCP_ALLOW_JSX=1 no ambiente do servidor.
TIMEOUT	A mensagem diz o que aconteceu: ainda em execução (termina sozinho: inspecione o estado antes de tentar novamente), ou descartado antes de começar porque o After Effects estava ocupado com outro comando (seguro tentar novamente). Uma caixa de diálogo modal aberta no After Effects bloqueia comandos.
AE_ERROR: aerender não encontrado	Defina AE_AERENDER para o caminho completo do executável aerender.
BAD_ARGS: O projeto nunca foi salvo	Salve o projeto uma vez (ou chame save_project com um caminho) e depois chame render_start novamente.
EXISTS em render_start	O arquivo de saída existe. Passe overwrite: true ou escolha outro caminho.
UNSUPPORTED em preview_frame	Sua versão do After Effects não tem saveFrameToPng. Atualize o After Effects.
AE_ERROR com a dica "ExtendScript line N"	N é uma linha do panel/host/host.jsx instalado; os banners // ---- host/<file> ---- lá mostram de qual arquivo de origem veio. Por favor, abra uma issue.
Unknown file extension ".ts" durante a instalação ou npm test	Seu Node.js é mais antigo que 22.18, que não pode executar arquivos .ts diretamente. Atualize o Node.js (node --version para verificar).
Alterações no servidor não aparecem	Execute npm run build e reinicie o servidor MCP pelo seu cliente. Alterações em host/ ou panel/ também precisam que o instalador seja executado novamente e o painel reaberto.
Os logs do painel estão em ~/Library/Logs/CSXS/ no macOS e %TEMP% (csxs*.log) no Windows.

Atualizações

Você fica sabendo de novas versões em três lugares:

• O painel do After Effects mostra a versão instalada e, quando existe uma versão mais recente, uma linha como v2.1.0 available com um botão Update to v2.1.0.
• Seu cliente de IA: get_project (geralmente a primeira chamada) inclui uma nota update com a nova versão e o comando a ser executado, para que o modelo possa informar você. Você também pode perguntar "check for updates" (check_for_updates).
• GitHub: os lançamentos são tags git vX.Y.Z; o que mudou está em CHANGELOG.md.

Como a verificação funciona: o servidor MCP consulta o GitHub pelas tags de versão do repositório no máximo uma vez por dia, em segundo plano, com um tempo limite curto, e armazena a resposta em cache em ~/.ae-motion-mcp/update.json (o painel apenas lê esse arquivo). Ele não envia nada além de uma solicitação anônima normal, e uma verificação com falha nunca afeta uma ferramenta. Defina AE_MCP_UPDATE_CHECK=0 para desativá-la.

Atualizando e desinstalando

Atualizar pelo painel: clique em Update to vX.Y.Z (ou Reinstall) no painel do AE Motion MCP e clique novamente para confirmar. Ele executa scripts/update.ts na sua pasta ae-motion, que faz o checkout da tag de lançamento mais recente (nunca trabalho não lançado em main) e executa o instalador, mostra a saída e reinicia o painel com a nova versão; em seguida, reinicie seu cliente de IA para que ele use o novo servidor. O checkout fica nessa tag (git switch main volta). O painel encontra a pasta e seu git / node / npm por meio de install.json, que o instalador grava, então um painel instalado antes desse botão existir precisa de uma atualização manual primeiro. Se você tiver alterações locais, ele para e avisa: faça commit ou stash delas, ou atualize manualmente.

Atualizar manualmente: na pasta do repositório, node scripts/update.ts (o lançamento mais recente, depois o instalador). Ou git pull para o main mais recente, e então execute o instalador novamente (bash scripts/install.sh, ou ./scripts/install.ps1 no Windows; ele reconstrói e substitui o painel instalado). Reabra o painel do AE Motion MCP (ou reinicie o After Effects) e reinicie o servidor MCP pelo seu cliente. A linha Version do painel mostra a nova versão.

Desinstalar:

1. Remova o servidor do seu cliente (claude mcp remove ae-motion, ou exclua a entrada da configuração do Claude Desktop).
2. Exclua a pasta do painel instalado (veja Instalação).
3. Exclua ~/.ae-motion-mcp/.
4. Opcional: desative novamente os painéis não assinados.
   • macOS: for v in 9 10 11 12; do defaults delete com.adobe.CSXS.$v PlayerDebugMode; done
   • Windows: exclua o valor PlayerDebugMode em HKCU\Software\Adobe\CSXS.9 para CSXS.12.

Documentação

• docs/tools.md: cada ferramenta, os modelos de linha do tempo e câmera e notas de comportamento
• docs/architecture.md: como as partes se encaixam, o protocolo de comunicação, a estrutura do repositório
• CONTRIBUTING.md: as regras para alterar o ae-motion e a lista de verificação pré-merge
• docs/development.md: compilação, testes, adição de uma ferramenta, peculiaridades do After Effects, status de verificação
• docs/future.md: mudanças que virão de fora do ae-motion, como a Adobe substituindo o CEP pelo UXP

Licença

MIT