Godot MCP

Godot MCP는 Godot Editor용 AI 기반 게임 개발 어시스턴트입니다. Claude, Cursor, Copilot 또는 모든 MCP 인식 에이전트를 Godot에 연결하여 프로젝트를 검사하고 구동할 수 있습니다 — 노드를 생성하고, 씬을 편집하며, 리소스와 스크립트를 관리하고, 스크린샷을 캡처하는 등 다양한 작업을 수행할 수 있습니다.

Godot-MCP는 Unity-MCP의 Godot 버전입니다. 이는 C# 에디터 애드온으로, Godot Editor의 기능을 AI Tools로 노출하여 동일한 호스팅 클라우드 백엔드(ai-game.dev)를 통해 MCP 서버에 연결합니다. 이 백엔드는 Unity-MCP가 사용하는 것과 같거나 자체 호스팅 서버를 사용할 수 있습니다. MCP / 리플렉션 스택은 포크되지 않았으며, nuget.org에서 PackageReference로 제공되는 Unity-MCP와 공유됩니다.

💬 저희 Discord 서버에 참여하여 질문하고, 작업물을 전시하며, 다른 개발자들과 연결하세요!

• ✔️ AI 에이전트 — Anthropic, OpenAI, Google 또는 기타 모든 공급자의 최고의 에이전트를 사용하여 벤더 종속성 없이 사용할 수 있습니다 - ✔️
  42개 내장 도구 — Godot Editor를 조작하기 위한 12가지 패밀리에 걸친 광범위한 MCP 도구 - ✔️
  C# 및 GDScript — .cs와 .gd 스크립트를 읽고, 생성하고, 업데이트하며 노드에 첨부할 수 있습니다 - ✔️
  씬 및 노드 제어 — 씬 트리를 구축하고 편집하며, .tscn 씬을 열거나 저장하고, .tres/.res 리소스를 변경할 수 있습니다 - ✔️
  시각적 피드백 — LLM이 검사할 수 있도록 뷰포트, 카메라, 격리된 노드의 스크린샷을 캡처합니다 - ✔️
  리플렉션 탈출구(Reflection escape hatch) — ReflectorNet을 통해 로드된 어셈블리 전체에서 모든 C# 메서드를 찾고 호출할 수 있습니다 - ✔️
  클라우드 또는 자체 호스팅 — 즉시 ai-game.dev에 연결하거나 자체 서버를 지정할 수 있습니다 - ✔️
  자연스러운 대화 — 사람과 이야기하듯이 AI와 채팅할 수 있습니다.

터미널에서 godot-cli를 사용하여 바로 시작할 수 있습니다. (이는 unity-mcp-cli의 Godot 버전입니다.) 수동 파일 복사나 csproj 편집이 필요 없습니다:

# 1. godot-cli 설치
npm install -g godot-cli
# 2. (선택 사항) 새로운 Godot C# 프로젝트를 스캐폴딩합니다 — 이미 존재하는 경우 건너뜁니다.
...

그게 전부입니다. AI에게 "반지름 2인 원형으로 큐브 3개 생성해줘"라고 요청하고 작동하는 것을 지켜보세요. ✨

오프라인/개발 설치:
install-plugin --source <path-to>/addons/godot_mcp

이 명령어는 애드온을 다운로드하는 대신 로컬 디렉토리에서 복사합니다. 특정 애드온 빌드가 필요하다면 install-plugin --version <x.y.z>를 사용하여 일치하는 릴리스 버전을 사용하는 것이 좋습니다. 수동 방식(애드온 복사 + NuGet 패키지 직접 추가)은 Asset Library / 수동 관리 흐름의 설치 단계 1–2에서 여전히 문서화되어 있습니다.

모든 명령어, 에디터 해결 순서 및 연결 환경 변수에 대한 전체 CLI 문서는 참고하십시오.

• 빠른 시작 (Quick Start)
• 도구 참조 (Tools Reference)
• 요구 사항 (Requirements)
• 설치 (Installation)
• 연결 (Connect)
• Godot
  MCP 서버

설정 - 도구 사용자 정의 (Customize Tools)

• 런타임 사용 (게임 내) (Runtime usage (in-game))
• Godot MCP 아키텍처 작동 방식 (How Godot MCP Architecture Works)
• 빌드 및 기여 (Building & contributing)
• 라이선스 (License)

Godot-MCP는 42개의 기본 도구를 포함하며, 이는 12개 패밀리로 그룹화되어 있습니다. 도구 이름은 적절한 경우 Unity-MCP와 유사합니다 (scene-*, node-*, …). 모든 도구는 구조화된 ReflectorNet 직렬화 결과(또는 스크린샷의 PNG 이미지)를 반환합니다. 모든 에디터 도구는 애드온이 활성화된 직후 즉시 사용할 수 있으며, 추가 구성은 필요하지 않습니다. 런타임 오류 (runtime-errors) 패밀리는 예외입니다: 이는 실행 중인 게임에서 발생하는 오류를 표시하며 기본적으로 비활성화되어 있습니다 — builder.WithRuntimeErrorCapture()로 옵트인하십시오(게임 내 런타임 오류 캡처 참조).

editor | editor-application-get-state, editor-application-set-state, editor-selection-get, editor-selection-set |
편집기 실행 및 재생 주기(Godot은 게임을 별도의 프로세스로 시작함)와 현재 선택된 항목을 읽거나 제어합니다. |
console | console-get-logs, console-clear-logs |
플러그인의 편집기 로그 수집기(GD.Print/GD.PushWarning/GD.PushError)를 읽고 지웁니다. |
reflection | reflection-method-find, reflection-method-call |
ReflectorNet을 통해 로드된 모든 어셈블리에서 C# 메서드(정적/인스턴스, public/private)를 찾고 호출합니다 — 엔진에 구애받지 않는 탈출구입니다. |
skills | godot-skill-create, godot-skill-generate |
프로젝트 내에 새로운 MCP 도구를 C# 파일로 작성하고, 편집기가 현재 등록한 도구들로부터 SKILL.md 파일을 재생성합니다. 시스템 도구 — 서버의 /api/system-tools/ HTTP 인터페이스를 통해 접근 가능하며(ping과 같은), tools/list에 AI 에이전트에게 광고되지는 않습니다. |
runtime-errors | runtime-errors-get, runtime-errors-clear |
실행 중인 게임(편집기가 아님) 내부에서 발생한 오류를 폴링합니다 — GDScript 런타임 오류, push_error/push_warning, 셰이더 오류, 그리고 C# 처리되지 않은/관찰되지 않은 Task 예외가 포함되며, Godot 4.5 이상에서는 다중 프레임 GDScript 백트레이스를 제공합니다. 기본적으로 비활성화되어 있으며, builder.WithRuntimeErrorCapture()로 옵트인해야 합니다.

ping

ping

— 경량 준비성 프로브(readiness probe); 메시지를 반향하거나 pong을 반환합니다. 시스템 도구: /api/system-tools/ping를 통해 호출합니다 (또는 godot-cli run-system-tool ping); tools/list에 나열되지 않습니다.

node

node-find
— 경로, 유형 또는 이름으로 활성 씬 트리에서 노드를 찾습니다. node-create
— 부모 아래에 새 노드를 생성합니다 (선택적으로 .tscn 서브 씬 인스턴싱). 선택적으로 특정 형제 index(끝에서부터 음수 카운트)에 배치할 수 있습니다. node-modify
— 하나 이상의 노드에 필드/속성을 설정합니다. node-set-parent
— 씬 트리 내에서 노드의 부모를 변경합니다. node-reorder

— 기존 노드를 형제(sibling) 중 다른 위치로 이동합니다 (Node.MoveChild<br/>)<br/>— 삭제하고 다시 생성하는 방법 외에, 기존 씬을 재배열할 수 있는 유일한 방법입니다.<br/>node-duplicate<br/>— 서브트리 전체와 함께 노드를 복제합니다.node-delete<br/>— 활성(active) 씬에서 노드를 삭제합니다.<br/><br/>scene (씬)<br/><br/>scene-open<br/>— 에디터에서 res://*.tscn 패키지화된 씬(PackedScene)을 엽니다.scene-save<br/>— 열려 있는 씬을 해당 .tscn 파일에 저장합니다.scene-create<br/>— 프로젝트에 새로운 씬 애셋을 생성합니다.scene-list-opened<br/>— 에디터에서 현재 열려 있는 씬 목록을 나열합니다.scene-get-data<br/>— 씬의 루트 노드/구조를 검색합니다.<br/><br/>resource (리소스)<br/><br/>resource-find<br/>— 프로젝트에서 리소스(.tres/.res)를 검색합니다.resource-get-data<br/>— 리소스의 직렬화된 필드와 속성을 읽습니다.resource-modify<br/>— 리소스의 속성을 수정합니다.resource-create<br/>— 새로운 리소스 애셋을 생성합니다.resource-move<br/>— 리소스를 이동하거나 이름을 변경하며, .import 사이드카를 일관되게 유지합니다.resource-delete<br/>— 프로젝트에서 리소스를 삭제합니다.<br/><br/>filesystem (파일 시스템)<br/><br/>filesystem-list<br/>— 에디터 파일 인덱스를 통해 res:// 트리(파일 유형 + uids)를 탐색합니다.filesystem-reimport<br/>— 프로젝트의 파일을 재가져오기(Reimport) 합니다.<br/><br/>script (스크립트)<br/><br/>script-read<br/>— .cs/.gd 스크립트 파일을 읽습니다.script-create<br/>— 새로운 스크립트 파일을 생성합니다.script-update<br/>— 기존 스크립트 파일의 내용을 업데이트합니다.script-delete<br/>— 스크립트 파일을 삭제합니다.script-attach-to-node<br/>— 노드에 스크립트를 부착합니다.script-validate<br/>— GDScript (.gd) 파일을 검증하고 구조화된 구문 분석/컴파일 진단(diagnostics)을 반환합니다.<br/><br/>screenshot (스크린샷)<br/><br/>screenshot-viewport<br/>— 에디터 뷰포트를 PNG로 캡처합니다.screenshot-camera<br/>— 특정 카메라에서 캡처합니다.screenshot-isolated<br/>— 선택된 각도에서 노드를 독립적으로 렌더링합니다.<br/><br/>editor (에디터)<br/><br/>editor-application-get-state<br/>— 에디터 애플리케이션/실행 상태를 읽습니다.editor-application-set-state<br/>— 실행 중인 게임을 시작하거나 중지합니다.editor-selection-get<br/>— 현재 에디터 선택 항목을 가져옵니다.`editor-selection-set

— 현재 에디터 선택 항목 설정.

console

console-get-logs

— 플러그인이 수집한 에디터 로그 읽기 (필터링 가능). 여기에는 플러그인의 연결 라이프사이클 진단(연결/연결 해제, drain-timeout, 설정 저장/로드, skill-gen, dev-control, dispatcher, 런타임-캡처 경고)이 포함되며, 이들은 프레임워크 로그와 동일한 캡처 싱크를 통해 라우팅됩니다. console-get-logs
console-clear-logs

— 수집된 로그 캐시 지우기.

reflection

reflection-method-find

— 로드된 모든 어셈블리에서 C# 메서드 찾기 (private 포함).reflection-method-call

— 입력 매개변수와 함께 모든 C# 메서드 호출하고 결과 받기.

runtime-errors (게임 내; 기본값 OFF — builder.WithRuntimeErrorCapture()로 활성화)

runtime-errors-get

— 캡처된 게임 내 런타임 오류 읽기 (오래된 순서부터, 최신 페이지 유지); sinceSequence를 통해 새로운 오류만 폴링합니다. 캡처가 한 번도 활성화되지 않은 경우 available:false를 반환하므로 빈 목록을 건강 상태로 오인하지 않습니다.runtime-errors-clear

— 캡처된 게임 내 런타임 오류 버퍼 지우기 (캡처가 비활성화된 경우 no-op); 단조 증가 시퀀스 카운터는 유지됩니다.

skills (시스템 도구 — /api/system-tools/에서 제공되며, AI 에이전트에게 광고되지 않음)

godot-skill-create

— 프로젝트에 새로운 C# (.cs) MCP 도구 파일 작성. 이 도구는 프로젝트가 재빌드되면 호출 가능해집니다 (Godot은 C#를 out-of-band로 빌드합니다).godot-skill-generate

— 현재 에디터에 등록된 모든 도구에서 SKILL.md 파일을 선택된 AI 에이전트의 스킬 폴더로 재생성합니다.

Godot 4.3+ — C# / .NET (mono) 에디션. 애드온 csproj는 최소 버전으로 Godot.NET.Sdk/4.3.0을 고정하며, 더 새로운 4.x 에디터(4.4, 4.5)도 작동합니다.NET 8 SDK(net8.0).

중요

Godot-MCP는 Godot의 mono (C#/.NET) 빌드를 필요로 합니다 — 표준 (GDScript 전용) 빌드는 애드온을 컴파일할 수 없습니다.

설치해야 할 두 가지가 있습니다: 애드온 (플러그인 파일)과 애드온의 C#이 의존하는 두 개의 NuGet 패키지. Godot은 모든 .cs

프로젝트 내의 모든 것을 하나의 어셈블리로 만들어, 프로젝트의 .csproj가 애드온이 필요로 하는 동일한 NuGet 참조를 선언해야 합니다. 그렇지 않으면 애드온의 C# 코드가 컴파일되지 않습니다.

다음 방법 중 하나를 선택하여 addons/godot_mcp/ 폴더를 Godot C# 프로젝트에 가져오세요.

완전 자동화 (터미널 워크플로우에 권장): godot-cli

install-plugin ./MyGodotProject

이 명령어는 단계 1과 단계 2를 한 번에 수행합니다. 일치하는 GitHub 릴리스에서 addons/godot_mcp/를 다운로드하고, 두 개의 NuGet 패키지와 확장 카탈로그를 <EmbeddedResource> .csproj에 추가하며, project.godot에서 플러그인을 **멱등적(idempotently)**으로 활성화합니다. 오프라인 상태에서 로컬 사본으로부터 설치하려면 --source <path>/addons/godot_mcp를 사용하세요. 아래의 수동 옵션 A–C는 에디터 내부 (Asset Library) 및 수동 관리 설치용으로 남아 있습니다.

가장 쉬운 방법: 에디터 내부에서 직접 설치합니다.

• Godot 에디터 상단의 AssetLib 탭을 엽니다. - Godot-MCP를 검색하고 애셋을 엽니다. - Download를 클릭한 다음 Install을 클릭하면, Godot이 애드온을 프로젝트의 res://addons/godot_mcp/에 압축 해제합니다.

Asset Library 항목은 릴리스별로 게시되며 항상 태그된 버전을 가리키므로, 에디터 내부 설치는 알려진 안정적인 스냅샷(known-good snapshot)을 제공합니다. (항목이 아직 보이지 않는 경우 아래 참고하세요.)

최신 godot-mcp-addon-<version>.zip를 다운로드