Instalação

Esta página mostra todas as formas de adicionar o Godot MCP a um projeto Godot C# e o que cada uma faz por você. Se você só quer que funcione, use o app desktop ou o godot-cli: ambos instalam o addon, ajustam seu .csproj e habilitam o plugin em um único passo. Os caminhos manuais (Asset Library, zip de release) exigem dois passos extras que são fáceis de esquecer.

Requisitos#

Opção 1: o app desktop AI Game Dev#

O app AI Game Dev pode instalar o Godot MCP em um projeto que você selecionar e então abrir o editor já conectado à sua conta. Ele traz sua própria cópia do instalador, então você não precisa de Node.js nem de npm. O app sempre instala o addon lançado mais recente e faz as mesmas três coisas que o godot-cli install-plugin: coloca os arquivos do addon em addons/godot_mcp/, adiciona os pacotes NuGet e o catálogo de extensões ao seu .csproj, e habilita o plugin em project.godot.

Baixe o app na página de download. Como instalá-lo e escolher um projeto está em Instalação do app; a linha de comando do app é descrita em CLI do app.

Opção 2: godot-cli (terminal)#

O godot-cli é o pacote npm do Godot MCP. Seu comando install-plugin é um instalador completo e pode ser executado novamente com segurança: uma segunda execução não altera nada.

npm install -g godot-cli
godot-cli install-plugin ./MyGodotProject

O que o install-plugin faz, em ordem:

1. Baixa godot-mcp-addon-<version>.zip do release do Godot-MCP no GitHub (HTTPS, somente github.com) e o coloca em res://addons/godot_mcp/. A versão padrão é a versão da própria CLI.
2. Adiciona ao seu .csproj os PackageReference do NuGet de que o addon instalado precisa, usando as versões do próprio addon, e corrige versões desatualizadas.
3. Adiciona o <EmbeddedResource> do catálogo de extensões e define <EnableDynamicLoading>true</EnableDynamicLoading>.
4. Habilita o plugin na seção [editor_plugins] do project.godot.

Variantes úteis:

# A specific addon release
godot-cli install-plugin --version 0.34.0 ./MyGodotProject

# Offline or development install from a local copy of the addon
godot-cli install-plugin --source ./Godot-MCP/addons/godot_mcp ./MyGodotProject

# No project yet: scaffold a Godot C# project first
godot-cli create-project --dotnet ./MyGodotProject

Você também pode executá-lo sem uma instalação global: npx godot-cli install-plugin ./MyGodotProject. Todas as flags estão listadas na referência do godot-cli.

Opção 3: Godot Asset Library#

1. No editor Godot, abra a aba AssetLib na parte superior.
2. Procure por Godot-MCP e abra o asset.
3. Clique em Download e depois em Install. O Godot descompacta o addon em res://addons/godot_mcp/.
4. Adicione os pacotes NuGet e a linha do catálogo ao seu .csproj (veja abaixo).
5. Habilite o plugin (veja abaixo).

A entrada na Asset Library sempre aponta para um release com tag, então você recebe um snapshot confiável. Ela contém apenas os arquivos do addon: os passos 4 e 5 ainda são por sua conta.

Opção 4: zip de release do GitHub ou cópia do código-fonte#

Baixe godot-mcp-addon-<version>.zip da página de releases do Godot-MCP e extraia na raiz do projeto. O arquivo já contém addons/godot_mcp/, então os arquivos ficam em res://addons/godot_mcp/. Você também pode copiar a pasta addons/godot_mcp/ de um clone do repositório. Em seguida, faça os dois passos manuais abaixo.

Passo manual: pacotes NuGet e o catálogo de extensões#

O Godot compila todos os arquivos .cs do seu projeto em um único assembly, então seu .csproj precisa referenciar os mesmos pacotes NuGet que o addon usa, senão o addon não vai compilar. Adicione isto ao seu .csproj (estas são as versões para o addon 0.34.0):

<ItemGroup>
  <PackageReference Include="com.IvanMurzak.ReflectorNet" Version="5.5.1" />
  <PackageReference Include="com.IvanMurzak.McpPlugin" Version="8.14.0" />
</ItemGroup>

<!-- Editor-only: exported games ship no RQL and no Roslyn. -->
<ItemGroup>
  <PackageReference Include="com.IvanMurzak.Rql" Version="0.3.0" Condition="'$(Configuration)' != 'ExportDebug' and '$(Configuration)' != 'ExportRelease'" />
  <PackageReference Include="com.IvanMurzak.CodeExec" Version="0.4.0" Condition="'$(GodotMcpCodeExecInGame)' == 'true' or ('$(Configuration)' != 'ExportDebug' and '$(Configuration)' != 'ExportRelease')" />
  <PackageReference Include="com.IvanMurzak.CodeExec.Roslyn" Version="0.4.0" Condition="'$(GodotMcpCodeExecInGame)' == 'true' or ('$(Configuration)' != 'ExportDebug' and '$(Configuration)' != 'ExportRelease')" />
  <PackageReference Include="Microsoft.CodeAnalysis.CSharp" Version="4.12.0" Condition="'$(GodotMcpCodeExecInGame)' == 'true' or ('$(Configuration)' != 'ExportDebug' and '$(Configuration)' != 'ExportRelease')" />
</ItemGroup>

<!-- Without this line the dock's Extensions list is empty. -->
<ItemGroup>
  <EmbeddedResource Include="addons/godot_mcp/extensions.catalog.json" LogicalName="Godot-MCP.extensions.catalog.json" />
</ItemGroup>

As versões precisam corresponder ao addon que você instalou. Cada release as lista no README, e o zip da release as traz em addons/godot_mcp/nuget-deps.json; o godot-cli install-plugin lê esse arquivo, e é por isso que ele nunca erra. O branch de desenvolvimento já avança o com.IvanMurzak.McpPlugin (8.18.0), então verifique novamente quando você atualizar.

Mantenha também o <EnableDynamicLoading>true</EnableDynamicLoading> no <PropertyGroup> do seu .csproj. O próprio template C# do Godot já o tem. Sem ele, um jogo iniciado com Play não consegue criar nenhum script C#.

Você não precisa copiar DLLs. Execute dotnet restore (ou compile a partir do Godot) e o addon encontra os pacotes no seu cache do NuGet em tempo de editor.

Etapa manual: habilitar o plugin#

Abra Project, Project Settings, Plugins e habilite Godot-MCP. Compile o projeto C# (o botão Build no editor, ou godot-cli build). Ao carregar com sucesso, o painel Output exibe:

[Godot-MCP] plugin loaded

O dock do AI Game Developer aparece na área de docks no canto superior direito. Continue com Primeiros passos.

Atualização e remoção#

• Atualize com a mesma ferramenta que você usou para instalar: execute novamente o godot-cli install-plugin (opcionalmente com --version), use o app, ou instale a nova release pela Asset Library e atualize as versões do NuGet manualmente.
• Atualize a própria CLI com godot-cli update.
• godot-cli remove-plugin ./MyGodotProject desabilita o addon em project.godot. Ele não exclui addons/godot_mcp/ nem as entradas do .csproj; remova-os manualmente se quiser que desapareçam.

Jogos exportados#

Os pacotes RQL, Code-Exec e Roslyn trazem uma Condition que os deixa de fora das builds ExportDebug e ExportRelease, então o jogo exportado não os inclui. As ferramentas de editor do addon são compiladas apenas no editor e nunca chegam a uma build do jogo. Expor ferramentas a partir de um jogo em execução é opcional e está descrito em Ferramentas personalizadas.