# 설치 — Godot · AI Game Developer Wiki

AI Game Dev 앱, godot-cli, Godot Asset Library 또는 릴리스 zip으로 Godot MCP 애드온을 설치하고, .csproj에 맞는 정확한 NuGet 패키지를 확인하세요.

이 페이지는 영어에서 기계 번역되었습니다. [영어 원문 읽기](https://ai-game.dev/docs/wiki/godot/installation).

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

## 요구 사항

| 요구 사항 | 세부 사항 |
| --- | --- |
| Godot | Godot 4.3 이상, **.NET (mono) 에디션**. 애드온은 `Godot.NET.Sdk` 4.3.0을 최소 버전으로 빌드되며, 프로젝트의 CI는 4.3, 4.4, 4.5, 4.6, 4.7에서 이를 구동해 확인합니다. |
| .NET | .NET 8 SDK(`net8.0`). |
| 프로젝트 | 루트에 C# `.csproj`가 있는 Godot 프로젝트. |
| `godot-cli`(선택 사항) | Node.js `^20.19.0` 또는 `>=22.12.0`. |
| 운영 체제 | Windows, macOS 또는 Linux. |

**경고**

표준 Godot 다운로드(GDScript 전용)로는 애드온을 컴파일할 수 없습니다. Godot의 .NET 빌드를 다운로드하세요. 프로젝트에 아직 `.csproj`가 없다면 Godot에서 (Project, Tools, C#, Create C# solution)로 생성하거나 `godot-cli create-project --dotnet`으로 새 프로젝트를 스캐폴딩하세요.

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

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

[다운로드 페이지](https://ai-game.dev/ko/download)에서 앱을 다운로드하세요. 앱을 설치하고 프로젝트를 선택하는 방법은 [앱 설치](https://ai-game.dev/ko/docs/wiki/app/installation)에, 앱의 명령줄은 [앱 CLI](https://ai-game.dev/ko/docs/wiki/app/cli)에 설명되어 있습니다.

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

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

```bash
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]` 섹션에서 플러그인을 활성화합니다.

유용한 변형:

```bash
# 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 레퍼런스](https://ai-game.dev/ko/docs/wiki/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 릴리스](https://github.com/IvanMurzak/Godot-MCP/releases/latest) 페이지에서 `godot-mcp-addon-<version>.zip`을 다운로드하여 프로젝트 루트에 압축을 풉니다. 아카이브에 이미 `addons/godot_mcp/`가 포함되어 있으므로 파일이 `res://addons/godot_mcp/`에 놓입니다. 저장소를 클론한 뒤 `addons/godot_mcp/` 폴더를 복사해도 됩니다. 그런 다음 아래의 두 가지 수동 단계를 수행하세요.

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

Godot은 프로젝트의 모든 `.cs` 파일을 하나의 어셈블리로 컴파일하므로, `.csproj`가 애드온이 사용하는 것과 동일한 NuGet 패키지를 참조해야 합니다. 그렇지 않으면 애드온이 컴파일되지 않습니다. `.csproj`에 다음을 추가하세요(애드온 0.34.0 기준 버전입니다):

```xml
<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>
```

| 패키지 | 버전(애드온 0.34.0) | 역할 |
| --- | --- | --- |
| `com.IvanMurzak.ReflectorNet` | 5.5.1 | 리플렉션 및 직렬화 코어 |
| `com.IvanMurzak.McpPlugin` | 8.14.0 | 에디터를 서버에 연결하는 MCP 클라이언트 |
| `com.IvanMurzak.Rql` | 0.3.0 | 에디터 도구들의 기반이 되는 쿼리 언어 RQL (에디터 전용) |
| `com.IvanMurzak.CodeExec` | 0.4.0 | `script-execute`용 C# 스니펫 실행 (옵트인하지 않는 한 에디터 전용) |
| `com.IvanMurzak.CodeExec.Roslyn` | 0.4.0 | Code-Exec용 Roslyn 어댑터 |
| `Microsoft.CodeAnalysis.CSharp` | 4.12.0 | Roslyn C# 컴파일러 |

버전은 설치한 애드온과 일치해야 합니다. 각 릴리스는 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 패널에 다음이 출력됩니다:

```text
[Godot-MCP] plugin loaded
```

**AI Game Developer** 독이 우측 상단 독 영역에 나타납니다. [Getting started](https://ai-game.dev/ko/docs/wiki/godot/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](https://ai-game.dev/ko/docs/wiki/godot/custom-tools)에 설명되어 있습니다.

---

Source (HTML): https://ai-game.dev/ko/docs/wiki/godot/installation

Machine-translated (ko) from the English page: https://ai-game.dev/docs/wiki/godot/installation