Esta página foi traduzida automaticamente do inglês. Leia o original em inglês.

Primeiros passos

Conecte o Godot MCP à nuvem, configure um agente de IA como o Claude Code, verifique a conexão e rode seus primeiros prompts no editor Godot.

Atualizado em 4 de novembro de 2026 Ver como Markdown

Esta página leva você de um addon instalado até um agente de IA que edita a sua cena Godot. Ela parte do princípio de que o addon já está no seu projeto; se não estiver, comece pela Instalação. Os passos usam o modo Cloud padrão, em que o editor e o seu agente se conectam a ai-game.dev e você faz login uma única vez.

Passo 1: abra o projeto

Abra o projeto com a CLI:

godot-cli open ./MyGodotProject

open compila o assembly C# primeiro e depois inicia o editor. A compilação é importante na primeira abertura: o Godot carrega os addons habilitados imediatamente e, sem um assembly compilado, informa que não consegue carregar GodotMcpPlugin.cs e desabilita o addon. Se você abrir o projeto pelo gerenciador de projetos do Godot, compile uma vez (o botão Build do editor ou godot-cli build) e reabilite o plugin caso o Godot o tenha desativado.

Quando o addon carrega, o painel Output do editor exibe [Godot-MCP] plugin loaded e o dock AI Game Developer aparece na área de docks no canto superior direito.

Passo 2: faça login

O modo Cloud precisa da sua conta ai-game.dev. Escolha uma destas opções:

  • No dock, mantenha o modo em Cloud e clique em Authorize. O navegador abre com um código curto; aprove-o com a sua conta ai-game.dev.
  • Em um terminal, execute godot-cli login. Ele usa o mesmo fluxo OAuth de dispositivo e salva a credencial em ~/.ai-game-dev/credentials.json, que o editor detecta sozinho.

Você faz login uma vez por máquina. A mesma credencial serve para o Godot MCP, o Unity MCP, o Unreal MCP, as CLIs dos engines e o app AI Game Dev. A sessão aparece nos dispositivos conectados da sua conta, onde você pode revogá-la. Detalhes: Autenticação.

Passo 3: conecte seu agente de IA

Escreva a configuração MCP para o agente que você usa. Para o Claude Code:

godot-cli setup-mcp claude-code ./MyGodotProject

Isso grava .mcp.json no projeto com uma URL vinculada a este projeto, para que o agente chegue a este editor mesmo quando você tem vários editores abertos. Você pode fazer o mesmo pelo dock: escolha seu agente na seção AI agent e clique em Configure. Outros agentes (Cursor, VS Code Copilot, Codex, Gemini e mais) estão listados em Conectando clientes de IA.

Reinicie o agente, ou recarregue os servidores MCP dele, depois que a configuração for gravada. Inicie o agente a partir da pasta do projeto quando a configuração estiver lá (o Claude Code lê .mcp.json da pasta em que é iniciado).

Passo 4: verifique a conexão

A seção Connection do dock mostra uma linha de três pontos: Godot, o servidor MCP e o agente de IA. Quando o editor está conectado e uma sessão de agente está ativa, os três ficam acesos e a linha do agente mostra o nome do cliente. Em um terminal, você também pode esperar o editor responder:

godot-cli wait-for-ready ./MyGodotProject
godot-cli status ./MyGodotProject

wait-for-ready consulta a sonda de prontidão (ping) até ela responder, por padrão por até dois minutos. status informa se há um editor em execução para o projeto e se o servidor responde.

No seu agente, peça para ele listar as ferramentas, ou execute /mcp no Claude Code. Você deve ver ferramentas como rql-query, rql-mutate, script-create e screenshot-viewport.

Passo 5: primeiros prompts

Experimente estes no chat do seu agente. Cada um corresponde a ferramentas reais, então você pode ver a cena mudar no editor:

  • "Adicione uma cena Node3D com uma Camera3D e um cubo MeshInstance3D, depois salve como Main.tscn."
  • "Crie 3 cubos em um círculo com raio 2."
  • "Liste todas as OmniLight3D da cena com a energia de cada uma."
  • "Crie um StandardMaterial3D para o piso e defina a cor albedo dele como cinza."
  • "Crie um script Player.cs com um float público Speed, anexe-o ao nó Player e compile o projeto."
  • "Adicione uma ação de entrada chamada jump na tecla Space."
  • "Tire um screenshot do viewport e me diga o que você vê."

As edições de cena feitas pelo agente podem ser desfeitas: pressione Ctrl+Z no editor para voltar, exatamente como nas suas próprias edições. As alterações de cena marcam a cena como não salva, então peça ao agente para salvar, ou salve você mesmo. Mais ideias de prompts estão em Boas práticas para Godot.

O que o agente pode e não pode ver

O agente trabalha por meio das ferramentas que o addon expõe. Ele pode ler a árvore de cena, as propriedades do Godot (incluindo variáveis GDScript), recursos, arquivos, configurações do projeto, o mapa de entrada, autoloads, o console e o estado do editor por meio do RQL, além de poder olhar screenshots. Ele não consegue clicar na interface do editor. A lista completa está em Ferramentas e no catálogo de ferramentas do Godot.

Prefere ficar offline?

Você pode executar o servidor MCP na sua própria máquina em vez de usar a nuvem. No dock, mude o modo para Custom e clique em Start Server: o addon baixa do GitHub o build do servidor correspondente, inicia-o e se conecta a ele. Depois, aponte seu agente para a URL local. Veja Conectando clientes de IA.

Próximos passos