문제 해결

대부분의 Godot MCP 문제는 네 가지 원인 중 하나에서 비롯됩니다: 잘못된 Godot 빌드, 애드온과 맞지 않는 .csproj, 빌드되지 않은 C# 어셈블리, 또는 올바른 서버를 가리키지 않는 AI 클라이언트입니다. 화면에 보이는 증상과 일치하는 섹션을 순서대로 확인하세요. 막혔다면 독의 Log Level을 Debug로 올리고 문제를 재현한 뒤 Output 패널을 읽어 보세요.

애드온이 로드되지 않음#

처음 열 때 "Unable to load addon script" 발생#

Godot은 에디터가 시작되자마자 활성화된 애드온을 인스턴스화합니다. 한 번도 빌드한 적 없는 C# 프로젝트를 처음 열면 어셈블리가 아직 없으므로, Godot은 res://addons/godot_mcp/Editor/GodotMcpPlugin.cs를 로드할 수 없다고 보고하고 애드온을 비활성화합니다.

해결 방법: 먼저 빌드한 다음 Project, Project Settings, Plugins에서 플러그인을 다시 활성화하세요.

godot-cli build ./MyGodotProject
godot-cli open ./MyGodotProject

godot-cli open은 항상 빌드한 뒤 에디터를 시작하므로 이 문제를 피할 수 있습니다.

애드온이 컴파일되지 않음#

• 표준 Godot 빌드를 사용하고 있습니다. Godot MCP는 Godot 4.3 이상의 .NET (mono) 빌드가 필요합니다.
• .csproj에 NuGet 패키지가 없거나, 설치한 애드온과 버전이 다릅니다. godot-cli install-plugin을 다시 실행하거나, Installation에서 사용 중인 애드온 릴리스 버전에 맞는 블록을 복사하세요.
• 프로젝트에 .csproj가 없습니다. Godot에서 C# 솔루션을 생성하거나, 새 프로젝트라면 godot-cli create-project --dotnet을 사용하세요.
• .NET 8 SDK가 설치되어 있지 않거나 PATH에 없습니다.

NuGet 어셈블리에 대한 FileNotFoundException#

Godot은 에디터에서 프로젝트의 NuGet 패키지를 스스로 확인하지 않습니다. 애드온이 빌드의 .deps.json과 NuGet 캐시를 읽어 이를 처리합니다. 그래도 어셈블리를 찾지 못하면 dotnet restore를 실행하고 다시 빌드하세요. 문제가 계속되면 .godot/mono/temp/obj와 .godot/mono/temp/bin을 삭제하고 다시 빌드하세요. 오래된 빌드 출력이 흔한 원인입니다.

Play로 시작한 게임이 C# 스크립트를 생성할 수 없음#

증상: EditorPlugin 클래스를 지목하는 TypeLoadException이 발생한 뒤 모든 C# 스크립트가 "Cannot instantiate C# script because the associated class could not be found"로 실패합니다. .csproj에 <EnableDynamicLoading>true</EnableDynamicLoading>가 빠져 있어 패키지 어셈블리가 게임 어셈블리 옆에 복사되지 않은 것입니다. <TargetFramework> 옆의 <PropertyGroup>에 이 항목을 추가하고 다시 빌드하세요. godot-cli install-plugin과 create-project는 이 설정을 자동으로 넣어 줍니다.

Extensions 목록이 비어 있음#

독은 컴파일된 프로젝트에서 확장 카탈로그를 읽습니다. .csproj에 다음 줄이 필요하며, 그다음 다시 빌드해야 합니다:

<EmbeddedResource Include="addons/godot_mcp/extensions.catalog.json" LogicalName="Godot-MCP.extensions.catalog.json" />

LogicalName은 정확히 Godot-MCP.extensions.catalog.json이어야 합니다. 독에서 .csproj를 찾을 수 없다고 표시되면 애드온이 Godot C# 프로젝트 안에 없는 것입니다. Extensions를 참고하세요.

에디터가 연결되지 않음#

• 클라우드 모드, 로그인하지 않음. 독에서 Authorize를 클릭하거나 godot-cli login을 실행하세요. 독에 로그인 상태가 표시됩니다.
• 환경 변수로 재정의됨. "Overridden by environment (GODOT_MCP_*)"라는 노란색 안내는 변수나 .env 파일이 모드나 호스트를 강제하고 있어 독에서 변경한 내용이 아무 효과가 없다는 뜻입니다. 해당 변수를 제거하거나 값을 변경하세요.
• 커스텀 모드, 서버 없음. 독에서 Start Server를 클릭하거나 직접 서버를 시작하세요. 오프라인일 때는 서버 다운로드가 Output 패널에 경고와 함께 실패하고 로컬 서버가 시작되지 않습니다. 클라우드 모드를 사용하거나 이미 가지고 있는 서버를 실행하세요.
• 원격 호스트에서 oauth를 사용하는 커스텀 모드. 애드온은 localhost 서버에만 계정 토큰을 보냅니다. 다른 호스트의 경우 GODOT_MCP_TOKEN을 설정하세요. 그렇지 않으면 "Refusing to send your ai-game.dev account token" 오류와 함께 연결이 실패합니다.

터미널에서 godot-cli status ./MyGodotProject와 godot-cli wait-for-ready ./MyGodotProject로 확인하세요.

AI 에이전트에 Godot 도구가 보이지 않음#

• 에이전트가 설정이 작성되기 전에 시작되었습니다. 에이전트를 다시 시작하거나 MCP 서버를 다시 로드하세요.
• Claude Code는 시작한 폴더에서 .mcp.json을 읽습니다. 프로젝트 폴더에서 시작하거나, 시작하는 위치에 설정을 작성하세요.
• 여러 에디터가 연결되어 있는데 에이전트가 단순한 /mcp URL을 사용하고 있습니다. setup-mcp가 기본으로 작성하는 고정 URL을 사용해 에이전트가 올바른 프로젝트에 접속하도록 하세요.
• 설정이 에디터와 다른 서버(클라우드 vs 로컬)를 가리키고 있습니다. 모드를 변경한 뒤 godot-cli setup-mcp <agent>를 다시 실행하거나 독에서 Reconfigure를 클릭하세요.
• 도구가 숨겨져 있습니다. 도크의 MCP 기능 섹션이나 godot-cli configure --list를 확인하세요. 숨겨진 도구는 에이전트에게 나열되지 않습니다.

C# 다시 빌드 중 도구 호출 실패#

Godot는 빌드된 DLL이 변경된 후 약 0.5초 뒤에 프로젝트의 C# 어셈블리를 다시 로드합니다(script-build, Build 버튼 또는 dotnet build). 애드온은 해당 어셈블리의 일부이므로 해제되었다가 다시 빌드되고 몇 초 안에 다시 연결됩니다. 다시 로드되는 시점에는 새 호출이 재시도 가능한 오류("Godot is about to reload the project's C# assembly … Retry in a few seconds")와 함께 거부됩니다. 기다렸다가 다시 시도하세요. script-build는 다시 로드된 후에 결과를 반환합니다.

.NET 10에서 다시 로드 후 에디터가 충돌하거나 멈춤#

이것은 .NET 런타임 버그입니다(dotnet/runtime#135441). .NET 10 서비스 수정이 배포될 때까지 에디터 프로세스에 이 환경 변수를 설정하고 Godot를 재시작하세요:

DOTNET_ThreadPool_ThreadsToKeepAlive=-1

Windows에서는 setx DOTNET_ThreadPool_ThreadsToKeepAlive -1로 설정할 수 있습니다. godot-cli open이나 exec로 시작한 에디터에는 자동으로 적용됩니다. .NET 런타임에 수정 사항이 포함되면 이 변수를 제거하세요.

호출이 이전 빌드로 전달됨#

도구 호출이 코드의 이전 버전처럼 동작한다면 같은 프로젝트에 에디터가 두 개 이상 연결되어 있을 수 있습니다. 예를 들어 잊고 있던 헤드리스 에디터가 그렇습니다. 여분의 에디터를 닫고(godot-cli close --owned-only는 godot-cli가 시작한 에디터를 닫습니다) 에디터 하나만 연결된 상태로 유지하세요.

빌드가 MissingMethodException으로 실패함#

프로젝트의 Godot.NET.Sdk 버전은 실행하는 에디터와 일치해야 합니다. 4.3을 대상으로 빌드된 프로젝트는 API가 바뀐 4.4 이상 에디터에서 MissingMethodException을 발생시킬 수 있습니다. .csproj의 Sdk="Godot.NET.Sdk/…" 버전을 에디터 버전에 맞게 업데이트하고 다시 빌드하세요.

여전히 해결되지 않는다면#

FAQ와 사이트 FAQ를 확인하거나, Output 패널 로그와 Godot, .NET, 애드온 버전을 함께 Godot-MCP 이슈 트래커에 문제를 보고하세요.