godot-mcp

Godot 4.x 프로젝트에서 AI 에이전트가 개발자와 똑같은 방식으로 작업할 수 있게 해주는 MCP 서버입니다. 씬을 읽고 편집하고, 스크립트를 작성하고, 빌드하고, 테스트하고, 실행하고, 결과를 확인하고, 문제가 생기면 디버깅할 수 있습니다.

파일 형식을 추측하거나 무턱대고 셸 명령을 실행하는 방식과 이 서버를 구분 짓는 두 가지는 다음과 같습니다:

• Godot 본인에게 묻습니다. 씬 및 리소스 파일은 구조적으로 파싱된 후 다시 직렬화됩니다(실제 프로젝트 파일 모음에 대한 왕복(round-trip) 시 바이트 단위로 동일함이 입증됨). 그러나 엔진 자체의 동작에 의존하는 부분 — C# 인트로스펙션, 셰이더 컴파일, 입력 바인딩, 에디터 상태 — 은 Godot의 의미를 메모리에서 재현하는 방식이 아니라, 실제로 Godot을 헤드리스로 실행하거나 실행 중인 에디터에게 질의함으로써 답을 얻습니다.

• 실패를 크게 알립니다. 이 프로젝트에서 측정 가능한 모든 실패 모드 — 디스플레이 없음, 빌드되지 않은 C# 어셈블리, 종료된 에디터, .NET이 아닌 바이너리 — 는 조용한 빈 결과가 아니라 고유한 이름을 가진 오류와 해결 방법으로 드러납니다. 근거가 되는 측정값은 docs/capability-matrix.md를 참고하세요. 그중 몇몇은 특히 직관적인 신호(종료 코드, null이 아닌 반환값)가 실은 거짓이었기 때문에 별도로 만들어진 것들입니다.

50가지 도구가 작업에 필요한 것에 따라 네 개의 계층으로 구성됩니다. 전체 참조는 docs/tools.md를, 도구가 거부했을 때 대처법은 docs/troubleshooting.md를 참고하세요.

요구 사항

• Node.js >= 20

• Godot 4.7+ 바이너리(기능 매트릭스는 4.7을 기준으로 측정했습니다. 다른 4.x 버전도 비슷하게 동작할 것으로 예상하지만 검증되지는 않았습니다)

• C# 도구를 쓰려면(build_csharp, run_tests, csharp_script_info, validate_node_property, validate_script 의 C# 스크립트 경로): .NET/mono 빌드 Godot — 일반 GDScript 전용 배포판은 .cs 스크립트를 로드하거나 인트로스펙션할 수 없으며, 모든 C# 도구는 이 사실을 시작부터 감지하여 중간에 실패하는 대신 NOT_MONO_BINARY로 거부합니다. Mono 빌드의 --version 출력에는 .mono.가 포함되어 있으며 같은 위치에 GodotSharp/ 디렉터리가 함께 제공됩니다.

• 특히 C# 도구에는 PATH에 dotnet SDK가 필요합니다. build_csharp와 run_tests는 dotnet을 직접 호출하고, csharp_script_info와 validate_node_property는 이미 존재하는 Debug 빌드가 필요하며 이는 build_csharp 또는 build_godot_artifacts가 만들어냅니다.

Related MCP server: godot-mcp-pilot

설치 및 빌드

git clone <this-repo> godot-mcp
cd godot-mcp
npm install
npm run build

이것으로 MCP 클라이언트가 실행할 진입점인 dist/server.js가 생성됩니다.

MCP 클라이언트 구성

클라이언트를 node로 dist/server.js를 가리키게 하고, Godot 바이너리를 찾을 수단을 지정해 주세요. 가장 간단한 설정은 GODOT_PATH를 명시적으로 지정하는 것입니다:

{
  "mcpServers": {
    "godot": {
      "command": "node",
      "args": ["/path/to/godot-mcp/dist/server.js"],
      "env": {
        "GODOT_PATH": "/path/to/Godot_v4.7-stable_mono_linux.x86_64"
      }
    }
  }
}

서버가 Godot 바이너리를 찾는 방법

다음 순서대로 우선순위를 갖으며, 가장 먼저 찾은 항목이 사용됩니다:

1. 도구 호출에 전달된 명시적 binary 인자.

2. GODOT_PATH 환경 변수.

3. 프로젝트 소유의 vendor/ 디렉터리에 포함된 바이너리(최대 3단계 하위까지 검색하며, 파일명에 mono가 포함된 것을 우대). 자체 Godot 빌드를 포함하여 배포하는 프로젝트용입니다.

4. PATH에 등록된 godot, godot4 또는 godot-mono.

서버가 프로젝트를 찾는 방법

다음 순서로 찾습니다:

1. 도구 호출에 전달된 명시적 project 인자.

2. GODOT_PROJECT 환경 변수.

3. 서버 프로세스의 작업 디렉터리에서 상위로 거슬러 올라가며 project.godot 파일을 탐색.

어떤 방법으로도 project.godot을 포함하는 디렉터리를 찾지 못할 경우, 프로젝트가 필요한 도구는 PROJECT_NOT_FOUND 오류로 실패합니다.

GODOT_MCP_DOCS_CACHE

godot_class_doc과 search_classes는 Godot 바이너리 자신에게 물어서 클래스 참조 인덱스를 만듭니다. 이 과정은 캐시할 만큼 느립니다. 인덱스는 기본적으로 $TMPDIR/godot-mcp-docs-cache/<godot-version>/ 디렉터리에 생성되며, GODOT_MCP_DOCS_CACHE를 설정하면 영구적인 위치에 저장할 수 있습니다. 캐시는 Godot 버전별로 구분되므로 바이너리를 업그레이드를 더 오래된 인덱스를 재사용하지 않고 새 인덱스로 다시 만듭니다. MCP 클라이언트가 대상 프로젝트 바깥의 작업 디렉터리에서 서버를 실행한다면, GODOT_PROJECT를 명시적으로 설정하세요:

{
  "mcpServers": {
    "godot": {
      "command": "node",
      "args": ["/path/to/godot-mcp/dist/server.js"],
      "env": {
        "GODOT_PATH": "/path/to/Godot_v4.7-stable_mono_linux.x86_64",
        "GODOT_PROJECT": "/path/to/your/godot-project"
      }
    }
  }
}

새 세션에서는 다른 무엇보다 먼저 godot_status를 호출하세요. 이 도구는 결정된 바이너리 경로, 버전, mono 빌드 여부, 디스플레이 접근 가능 여부, 프로젝트 루트, C# 어셈블리 빌드 여부를 보고합니다. 그래서 에이전트(또는 당신)가 아무것도 시도하기 전에 실제로 무엇이 가능한지 알 수 있습니다.

네 가지 계층

모든 도구는 그 도구가 답할 수 있는 가장 낮은 계층에서 제공됩니다. 도구가 TIER_UNAVAILABLE 또는 DISPLAY_REQUIRED로 실패한다면 그 이유가 바로 이것입니다:

Tier D는 별도의 전송 방식이 아니라 Tier B 위에 얹은(tier) 기능 제약입니다. capture_screenshot만이 Tier D입니다. Godot에는 헤드리스 렌더링 경로가 없기 때문에 스크린샷은 가상이든 물리적이든 실제 디스플레이가 필요합니다. run_project를 windowed: true로 실행하는 경우에도 동일한 요구사항이 적용됩니다.

Tier A 도구(대부분의 씬, 노드, 스크립트, 프로젝트 설정 편집)는 Godot이 전혀 설치되지 않는 병법에서도 동작합니다. 이들은 순수 파일 연산으로, 실제 .tscn/.tres/project.godot 파일들의 모음(corpus)에 대한 왕복 바이트 동일성 테스트로 검증됩니다. 계층 B는 Godot 바이너리 및/또는 PATH에서 찾은 dotnet이 필요합니다. 계층 C는 에디터 애드온(다음 섹션)이 필요합니다. 애드온이 설치되고 활성화된 에디터가 가동 중이 아니면, 다섯 개의 에디터 브리지 도구가 모두 TIER_UNAVAILABLE로 실패합니다. 이는 버그가 아니라 예상한 상황이며, 오류 메시지가 두 가지 기 상이한 상황 중 어느 쪽인지 알려줍니다(docs/troubleshooting.md 참고).

모든 도구의 계층은 docs/tools.md에서 확인하면.

에디터 애드온 설치 (Tier C)

다섯 가지 도구 — editor_state, get_selected_node, live_scene_tree, open_scene_in_editor, execute_editor_script — 는 표준 프로세스를 실행하는 대신 루프백 TCP 소켓으로 실행 중인 Godot 에디터와 대화합니다. 이를 위해서는 대상 프로젝트에 설치되고 활성화되어 있는 작은 GDScript 에디터 애드온이 필요합니다. 설치 도구는 없습니다. 사용자의 addons/ 디렉터리에 쓰거나 그들의 project.godot을 마이그레이션하는 것은 이 프로젝트의 기본 원칙인 path-jail 규율이 자동으로 실행하는 것을 피하려는 일입니다. 일회성 수동 단계는 다음과 같습니다:

1. 이 저장소의 addon/godot_mcp/ 폴더를 대상 프로젝트의 addons/ 디렉터리로 복사하여 <project>/addons/godot_mcp/plugin.cfg가 되도록 한다.

2. 플러그인을 활성화합니다 — 에디터에서(Project Settings > Plugins > godot_mcp > Enable) 또는 project.godot에 직접 추가해서:

   [editor_plugins]
   
   enabled=PackedStringArray("res://addons/godot_mcp/plugin.cfg")

3. 해당 프로젝트에서 Godot 에디터를 실행(또는 재시작)합니다 —헤드리스(headless)여도 됩니다(--headless --editor --path <project>), 디스플레이는 불필요. 애드온은 시작 시 <project>/.godot/mcp_bridge.json에 핸드셰이크 파일을 기록합니다. 다섯 도구는 이 파일을 열어 브리지의 포트와 세션별 토큰을 알아냅니다.

헤드리스 에디터에서는 선택 상태가 항상 빈 것은 예상된 동작입니다(get_selected_node는 "선택된 것 없음"을 오류가 아닌 일반 결과로 보고합니다).

안전과 범위

• 경로 격리. 모든 쓰기 경로 — 씬, 스크립트, 리소스, 스크린샷 결과 —는 실제 경로로 해석되어 프로젝트 루트 안에 있어야 합니다. 그것을 벗어나거나 심볼릭 링크를 통한 한채에서 다른 위치로 향하는 경로는 아무것도 건드리기 전에 PATH_OUTSIDE_PROJECT 오류로 거부됩니다.

• dry_run. 모든 변경 가능 도구는 dry_run을 받아들여 쓰기 대신 통합 diff를 반환합니다. 커밋하기 전에 변경 사항을 미리 살펴보는 데 사용하세요.

• 백업 저장소 없음. 버전 관리가 곧 실행 취소 시스템입니다. 이것은 의도한 단순화입니다. 서버 자체에는 스냅샷이나 백업 메커니즘이 없습니다. 프로젝트가 버전 관리 하에 있지 않다면 변경 호출 이전에 dry_run을 사용하거나 버전 관리를 시작하세요.

• execute_editor_script은 샌드박스가 아닙니다. 실제 동작 중인 에디터 프로세스 안에서 임의의 GDScript 실행하며, 에디터 자신과 같은 권한을 갖습니다. 실행 중인 에디터 상태, 열려 있는 씬, GDScript로 닿을 수 있는 모든 것을 읽고 변경할 수 있습니다. 이것은 에이전트에 셸(shell)을 건내주는 것과 같게 생각하세요. 신뢰할 수 있는 에이전트가 자기 프로젝트에서 사용하는 것은 적절하지만, 신뢰할 수 없는 입력에는 적합하지 않습니다.

테스트

npm test

tsc --noEmit을 ’tsconfig.json과 tsconfig.test.json 양쪽에 실행한 후 전체 Vitest 스위트를 실행합니다. 거의 모든 테스트는 파서 수준입니다. 즉, Godot/MSBuild의 준비된 출력을 파서에 주입하고 구조화된 결과를 검사합니다. 따라서 이 스위트는 Godot 설치가 없어도 되고 .NET 툴체인도 필요 없어 빠르고 이식 가능합니다(CI, 컨테이너, 둘 다 설치되지 않은 랩톱).

GODOT_TEST_BINARY

두 블록은 특별합니다. tests/integration/tier-b.test.ts는 실제 Godot 바이너리를 사용합니다. 일부러 디스크에 임시 프로젝트를 만들고, it를 대상으로 validate_script, check_shaders, run_project, godot_class_doc을 호출합니다. 파서는 초기받은 텍스트를 통해 계속 테스트할 수 있어도, 도구 자체의 프로세스 실행, 인자 생성, 출력 스트림 읽기 코드가 실제 실제 엔진에서 제대로 작동한다는 증명이 되지 않기 때문입니다. tests/integration/tier-c.test.ts는 에디터 브리지 도구에 대해 동일한 것을 실행하는데 그 요구사항은 확실히 다릅니다. 실제 Godot 에디터를 오래 유지되는 반접(분리된) 프로세스로 시작하고(에디터는 스스로 종료하지 않음), 테스트가 실패한 경우에도 그 뒤에서 반드시 그 프로세스를 정리해야 합니다.

• 설정하지 않음 (기본값): 두 블록 모두 SKIPPED로 표시됩니다. npm test의 다른 부분은 영향받지 않습니다.

• Godot 4.7+ 바이너리 경로를 지정: 두 블록이 실제로 그 바이너리로 종단간 실행됩니다.

GODOT_TEST_BINARY=/path/to/Godot_v4.7-stable_linux.x86_64 npm test

이 블록에는 mono/.NET 빌드가 필요하지 않습니다. C# 관련 도구(build_csharp, run_tests) 작업을 하고 있다면 별도로 PATH에 dotnet이 있었고 싶을 수도 있는데, 현재 그에 상응하는 게이트 변수는 없으며 GODOT_TEST_BINARY 블록의 어떤 테스트도 그걸 필요로 하지 않기 때문입니다.

문서

• docs/tools.md — 모든 도구를 영역별로 그룹화, 티어와 주요 입력값 포함

• docs/troubleshooting.md — 측정된 오류 모드와 해결 방법

• docs/capability-matrix.md — 이 프로젝트 행동의 근거가 된 경험적 측정치