설치

이 페이지는 Godot MCP를 Godot C# 프로젝트에 추가하는 모든 방법과 각 방법이 무엇을 해 주는지 보여 줍니다. 그냥 바로 동작하게 하고 싶다면 데스크톱 앱이나 godot-cli를 사용하세요. 둘 다 애드온 설치, .csproj 패치, 플러그인 활성화를 한 번에 처리합니다. 수동 경로(Asset Library, 릴리스 zip)는 놓치기 쉬운 두 가지 추가 단계가 필요합니다.

요구 사항#

옵션 1: AI Game Dev 데스크톱 앱#

AI Game Dev 앱은 선택한 프로젝트에 Godot MCP를 설치한 다음, 이미 계정에 연결된 상태로 에디터를 열 수 있습니다. 설치 프로그램 사본을 자체적으로 포함하고 있어 Node.js나 npm이 필요하지 않습니다. 앱은 항상 최신 릴리스 애드온을 설치하며 godot-cli install-plugin과 동일한 세 가지 작업을 수행합니다. 애드온 파일을 addons/godot_mcp/에 넣고, NuGet 패키지와 확장 카탈로그를 .csproj에 추가하고, project.godot에서 플러그인을 활성화합니다.

다운로드 페이지에서 앱을 다운로드하세요. 앱을 설치하고 프로젝트를 선택하는 방법은 앱 설치에, 앱의 명령줄은 앱 CLI에 설명되어 있습니다.

옵션 2: godot-cli (터미널)#

godot-cli는 Godot MCP용 npm 패키지입니다. install-plugin 명령은 완전한 설치 프로그램이며 다시 실행해도 안전합니다. 두 번째 실행에서는 아무것도 변경되지 않습니다.

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

install-plugin이 수행하는 작업(순서대로):

1. Godot-MCP GitHub 릴리스(HTTPS, github.com 전용)에서 godot-mcp-addon-<version>.zip을 다운로드하여 res://addons/godot_mcp/에 넣습니다. 버전은 기본적으로 CLI 자체 버전을 따릅니다.
2. 설치된 애드온에 필요한 NuGet PackageReference를 .csproj에 추가하며, 버전은 애드온 자체에서 가져오고 오래된 버전은 바로잡습니다.
3. 확장 카탈로그 <EmbeddedResource>를 추가하고 <EnableDynamicLoading>true</EnableDynamicLoading>을 설정합니다.
4. project.godot의 [editor_plugins] 섹션에서 플러그인을 활성화합니다.

유용한 변형:

# 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

전역 설치 없이도 실행할 수 있습니다: npx godot-cli install-plugin ./MyGodotProject. 모든 플래그는 godot-cli 레퍼런스에 나열되어 있습니다.

옵션 3: Godot Asset Library#

1. Godot 에디터에서 상단의 AssetLib 탭을 엽니다.
2. Godot-MCP를 검색하고 에셋을 엽니다.
3. Download를 클릭한 다음 Install을 클릭합니다. Godot이 애드온을 res://addons/godot_mcp/에 풀어 놓습니다.
4. NuGet 패키지와 카탈로그 줄을 .csproj에 추가합니다(아래 참조).
5. 플러그인을 활성화합니다(아래 참조).

Asset Library 항목은 항상 태그가 지정된 릴리스를 가리키므로 검증된 스냅샷을 얻을 수 있습니다. 애드온 파일만 포함되어 있으므로 4단계와 5단계는 여전히 직접 수행해야 합니다.

옵션 4: GitHub 릴리스 zip 또는 소스 복사본#

Godot-MCP 릴리스 페이지에서 godot-mcp-addon-<version>.zip을 다운로드하여 프로젝트 루트에 압축을 풉니다. 아카이브에 이미 addons/godot_mcp/가 포함되어 있으므로 파일이 res://addons/godot_mcp/에 놓입니다. 저장소를 클론한 뒤 addons/godot_mcp/ 폴더를 복사해도 됩니다. 그런 다음 아래의 두 가지 수동 단계를 수행하세요.

수동 단계: NuGet 패키지와 확장 카탈로그#

Godot은 프로젝트의 모든 .cs 파일을 하나의 어셈블리로 컴파일하므로, .csproj가 애드온이 사용하는 것과 동일한 NuGet 패키지를 참조해야 합니다. 그렇지 않으면 애드온이 컴파일되지 않습니다. .csproj에 다음을 추가하세요(애드온 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>

버전은 설치한 애드온과 일치해야 합니다. 각 릴리스는 README에 해당 버전을 나열하며, 릴리스 zip에는 addons/godot_mcp/nuget-deps.json에 버전이 들어 있습니다. godot-cli install-plugin이 바로 이 파일을 읽기 때문에 버전이 틀리는 일이 없습니다. 개발 브랜치에서는 이미 com.IvanMurzak.McpPlugin이 앞서 나가 있으므로(8.18.0), 업데이트할 때 다시 확인하세요.

또한 .csproj의 <PropertyGroup>에 <EnableDynamicLoading>true</EnableDynamicLoading>을 유지해야 합니다. Godot 자체 C# 템플릿에도 이 설정이 들어 있습니다. 이 설정이 없으면 Play로 게임을 실행했을 때 C# 스크립트를 생성할 수 없습니다.

DLL을 복사할 필요는 없습니다. dotnet restore를 실행하거나 Godot에서 빌드하면, 애드온이 에디터 시점에 NuGet 캐시에서 패키지를 찾습니다.

수동 단계: 플러그인 활성화#

Project, Project Settings, Plugins를 열고 Godot-MCP를 활성화하세요. C# 프로젝트를 빌드하세요(에디터의 Build 버튼 또는 godot-cli build). 로드에 성공하면 Output 패널에 다음이 출력됩니다:

[Godot-MCP] plugin loaded

AI Game Developer 독이 우측 상단 독 영역에 나타납니다. Getting started에서 계속하세요.

업데이트 및 제거#

• 설치할 때 사용한 것과 같은 도구로 업데이트하세요. godot-cli install-plugin을 다시 실행하거나(원하면 --version 사용), 앱을 사용하거나, Asset Library에서 새 릴리스를 설치한 뒤 NuGet 버전을 직접 갱신하면 됩니다.
• CLI 자체는 godot-cli update로 업데이트하세요.
• godot-cli remove-plugin ./MyGodotProject는 project.godot에서 애드온을 비활성화합니다. addons/godot_mcp/나 .csproj 항목을 삭제하지는 않으므로, 없애려면 직접 제거하세요.

내보낸 게임#

RQL, Code-Exec, Roslyn 패키지는 Condition을 포함하고 있어 ExportDebug 및 ExportRelease 빌드에서 제외되므로, 내보낸 게임에 이 패키지들이 포함되지 않습니다. 애드온의 에디터 도구는 에디터에서만 컴파일되며 게임 빌드에는 포함되지 않습니다. 실행 중인 게임에서 도구를 노출하는 것은 선택 사항이며 Custom tools에 설명되어 있습니다.