Como usar o Claude Code com o Unity Engine

O Claude Code é um dos melhores agentes de IA disponíveis, alimentado por modelos como o Opus 4.5. Neste tutorial, vamos conectá-lo diretamente ao Unity Engine para que ele possa ler suas cenas, chamar APIs do Unity e modificar seu projeto — tudo pelo terminal.

O que você precisa

• Unity 2021.3 ou mais recente
• Node.js ^20.19.0 ou >=22.12.0 (para a CLI)
• Claude Code instalado (agente de IA baseado em terminal)
• AI Game Developer — a ponte entre agentes de IA e o Unity: github.com/IvanMurzak/Unity-MCP

Instalando o AI Game Developer

O AI Game Developer funciona como uma ponte entre agentes e modelos avançados de IA e o Unity Engine. Você pode instalá-lo manualmente pelo Unity Editor ou usar a CLI para uma configuração totalmente automatizada.

Opção A: instalação manual (Unity Editor)

1. Baixe o instalador na página do AI Game Developer no GitHub
2. Dê um duplo clique no arquivo do instalador para abri-lo no Unity
3. Clique em "Import" na janela de importação do Unity
4. Aguarde o Unity terminar a compilação

Opção B: instalação pela CLI (recomendada)

A ferramenta unity-mcp-cli automatiza toda a configuração pela linha de comando — sem cliques manuais. Instale-a globalmente e use-a para adicionar o plugin a qualquer projeto Unity.

# Install the CLI globally
npm install -g unity-mcp-cli

# Install the AI Game Developer plugin into your Unity project
unity-mcp-cli install-plugin ./MyUnityProject

O comando install-plugin modifica diretamente o Packages/manifest.json do seu projeto — ele adiciona o registro com escopo OpenUPM e a dependência do plugin. Ele nunca faz downgrade de uma instalação existente. Depois de executá-lo, abra o projeto no Unity para concluir a instalação do pacote.

Configurando a conexão

Assim que o pacote é importado, a janela do AI Game Developer aparece. Role para baixo até a seção do Claude Code e clique em "Configure" — essa é toda a configuração necessária. Depois, clique em "Connect" para iniciar o processo de conexão. No começo você verá erros porque o Claude Code ainda não está em execução — isso é esperado.

CLI: configurar o MCP para o Claude Code

A CLI pode configurar automaticamente a integração MCP para o Claude Code — sem precisar da interface do Unity Editor. Ela grava os arquivos de configuração corretos para que o Claude Code encontre o servidor do AI Game Developer ao iniciar.

# Configure Claude Code MCP integration
unity-mcp-cli setup-mcp claude-code ./MyUnityProject

# Generate skill files so Claude Code knows about available tools
unity-mcp-cli setup-skills claude-code ./MyUnityProject

Iniciando o Claude Code

Você pode iniciar o Claude Code pelo Visual Studio Code ou diretamente pelo terminal. Neste tutorial, usamos a abordagem pelo terminal. Abra o terminal na pasta do seu projeto Unity — você pode fazer isso clicando com o botão direito na pasta Assets no Unity, selecionando "Show in Explorer", depois clicando com o botão direito e escolhendo "Open in Terminal".

# Navigate to your Unity project folder and start Claude Code
cd /path/to/your/unity/project
claude

Quando o Claude Code inicia, o status na janela do AI Game Developer muda para "Connected". Para verificar se tudo está funcionando, digite /mcp no Claude Code — você deve ver "AI Game Developer" listado e conectado.

Testando a IA na sua cena do Unity

Com a conexão estabelecida, tente perguntar à IA algo como "O que você vê nesta cena do projeto Unity?". A IA usará as ferramentas MCP fornecidas pelo AI Game Developer para ler a hierarquia da sua cena, inspecionar os GameObjects e relatar o que encontrou. Ela itera passo a passo — lendo os dados da cena, examinando objetos aninhados e montando um quadro completo do seu projeto.

Quando o Claude Code pedir permissão para usar uma ferramenta, você pode escolher a opção 2 para permitir e pular os próximos avisos da mesma ferramenta. A IA então lerá sua cena, identificará objetos como meshes, luzes e hierarquias aninhadas, e fornecerá uma descrição detalhada de tudo o que encontrou.

Otimizando o contexto

O AI Game Developer expõe muitas ferramentas MCP à IA. Uma dica importante: desative as ferramentas que você não precisa. Cada ferramenta ativada consome contexto da IA, e manter o contexto limpo permite que a IA trabalhe com mais eficiência e produza melhores resultados. Você pode ativar e desativar ferramentas na janela do AI Game Developer — ou usar a CLI.

# List current tool/prompt/resource configuration
unity-mcp-cli configure ./MyUnityProject --list

# Enable only the tools you need
unity-mcp-cli configure ./MyUnityProject \
  --enable-tools rql-query,rql-mutate,rql-schema,script-update-or-create \
  --disable-all-prompts

# Or enable everything at once
unity-mcp-cli configure ./MyUnityProject \
  --enable-all-tools \
  --enable-all-prompts

• Desative as ferramentas que você não usa para manter o contexto da IA enxuto
• Considere desativar os Resources se você não precisar deles
• Os prompts são comandos de barra — digite / no Claude Code para ver comandos disponíveis, como "set up an animation" ou "add a component"
• Confira o indicador de status Connected para confirmar que a conexão está ativa

O que você pode fazer a partir daqui

Com o Claude Code conectado ao Unity, você pode pedir à IA qualquer coisa que as ferramentas MCP suportem — inspecionar cenas, criar GameObjects, modificar componentes, gerar animações, montar UI e muito mais. A IA tem acesso a um conjunto abrangente de ferramentas e pode chamar qualquer uma delas com base nos seus prompts em linguagem natural.

Você também pode executar ferramentas MCP diretamente pela linha de comando, sem passar pela IA, o que é útil para scripts e pipelines de CI.

# Check connection status at a glance
unity-mcp-cli status ./MyUnityProject

# Run an MCP tool directly from the CLI
unity-mcp-cli run-tool rql-query ./MyUnityProject --input '{"query":"objects | where name == \"Player\" | select $ref name transform.position"}'

# Run Unity tests via MCP
unity-mcp-cli run-tool tests-run ./MyUnityProject --input '{"testMode":"EditMode"}'

Automação completa: do zero à conexão

A CLI pode automatizar todo o fluxo de trabalho — criar um projeto, instalar o plugin, configurar o Claude Code, abrir o Unity, aguardar a conexão e executar ferramentas. Aqui está um script completo que configura tudo do zero.

# 1. Create a new Unity project
unity-mcp-cli create-project ./MyAIGame --unity 6000.3.1f1

# 2. Install the AI Game Developer plugin
unity-mcp-cli install-plugin ./MyAIGame

# 3. Enable all MCP tools
unity-mcp-cli configure ./MyAIGame --enable-all-tools

# 4. Configure Claude Code MCP integration
unity-mcp-cli setup-mcp claude-code ./MyAIGame

# 5. Open the project with MCP connection
unity-mcp-cli open ./MyAIGame --keep-connected

# 6. Wait for Unity and MCP server to be ready
unity-mcp-cli wait-for-ready ./MyAIGame

# 7. Generate Claude Code skills
unity-mcp-cli setup-skills claude-code ./MyAIGame

# 8. Verify by running a tool
unity-mcp-cli run-tool tests-run ./MyAIGame --input '{"testMode":"EditMode"}'

Comece agora

O AI Game Developer é open source. Instale o pacote do Unity, configure o Claude Code e comece a fazer prompts. A ferramenta de CLI está disponível no npm para fluxos de trabalho automatizados. Consulte o guia de início rápido em ai-game.dev/docs/quickstart para instruções detalhadas de configuração.

• AI Game Developer (Unity-MCP): github.com/IvanMurzak/Unity-MCP
• Extensão de animação de IA: github.com/IvanMurzak/Unity-MCP/blob/main/extensions/Animation/README.md
• Ferramenta de CLI: npmjs.com/package/unity-mcp-cli
• Download: ai-game.dev/download
• A seguir: gerar animações com IA — ai-game.dev/blog/generating-unity-animations-with-ai