# Godot MCP — AI Game Developer Wiki

Godot MCP는 Claude, Cursor, Copilot 등 AI 에이전트를 Godot 에디터에 연결합니다. 설치, 설정, 도구, 확장, CLI는 여기서 시작하세요.

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

Godot MCP는 AI Game Developer의 Godot 애드온입니다. Claude Code, Cursor, GitHub Copilot, Codex, Gemini 같은 AI 에이전트가 Godot 에디터 안에서 작업할 수 있게 해줍니다. 씬 트리를 조회하고 편집하며, `.tscn` 씬을 열고 저장하고, `.tres` 리소스와 프로젝트 설정을 변경하고, C# 및 GDScript 파일을 읽고 쓰고, C# 프로젝트를 빌드하고, 에디터에서 C# 스니펫을 실행하고, 모델이 볼 수 있는 스크린샷을 찍을 수 있습니다. 이 위키에서는 설치 방법, AI 클라이언트 연결 방법, 일상적인 사용 방법을 설명합니다.

## Godot MCP란 무엇인가

Godot MCP는 Godot 4 .NET 프로젝트 안에서 실행되는 C# 에디터 애드온입니다(폴더 `addons/godot_mcp/`, Project Settings에 **Godot-MCP**로 표시됨). 에디터가 이 애드온을 로드하면 **AI Game Developer**라는 독을 열고 MCP 서버에 연결합니다. 대화하는 AI 에이전트도 같은 서버에 연결되어 Model Context Protocol(MCP)을 통해 애드온의 도구를 호출합니다.

이 애드온은 오픈 소스(Apache-2.0)이며 [Godot-MCP 저장소](https://github.com/IvanMurzak/Godot-MCP)에 있습니다. Unity MCP, Unreal MCP와 MCP 및 리플렉션 라이브러리를 공유하므로 세 엔진 플러그인이 동일하게 동작하고 같은 클라우드 계정을 사용합니다.

## 구성 요소들의 관계

| 구성 요소 | 하는 일 |
| --- | --- |
| Godot MCP 애드온 | Godot 에디터에서 실행되며 AI 도구를 노출하고 MCP 서버에 연결합니다. |
| MCP 서버 | [ai-game.dev](https://ai-game.dev)의 클라우드 서버(기본값) 또는 사용자 컴퓨터에서 실행되는 자체 서버입니다. |
| AI 클라이언트 | Claude Code, Cursor, VS Code Copilot, Codex, Gemini 또는 기타 MCP 클라이언트입니다. 같은 서버에 연결됩니다. |
| `godot-cli` | 애드온을 설치하고, 로그인하고, AI 클라이언트 설정을 작성하고, 에디터를 여는 npm 명령줄 도구입니다. |
| AI Game Dev 앱 | 터미널 없이 애드온을 설치하고 에디터를 열어 줄 수 있는 데스크톱 앱입니다. |

기본 클라우드 모드에서는 Godot과 AI 클라이언트 외에는 사용자 컴퓨터에서 실행되는 것이 없습니다. 에디터와 에이전트가 모두 호스팅 엔드포인트에 연결되며, ai-game.dev 계정으로 한 번만 로그인하면 됩니다. 커스텀 모드에서는 애드온이 로컬 MCP 서버를 다운로드해 시작할 수 있어 모든 것이 사용자 컴퓨터 안에 머뭅니다.

## 필수 요구 사항 한눈에 보기

- **Godot 4.3 이상의 .NET (mono) 빌드**. GDScript 전용 표준 빌드로는 애드온을 컴파일할 수 없습니다.
- **.NET 8 SDK**.
- C# `.csproj`가 있는 Godot 프로젝트. 게임 코드 자체는 여전히 GDScript여도 괜찮습니다. 애드온은 자기 자신을 컴파일하기 위해서만 C# 프로젝트가 필요합니다.
- MCP를 지원하는 AI 클라이언트.

`.csproj`에 필요한 NuGet 패키지를 포함한 전체 목록은 [설치](https://ai-game.dev/ko/docs/wiki/godot/installation)에 있습니다.

## 빠른 시작

터미널이 익숙하다면 다음 명령으로 Godot C# 프로젝트를 아무것도 없는 상태에서 연결된 AI 에이전트까지 한 번에 설정할 수 있습니다.

```bash
npm install -g godot-cli
godot-cli install-plugin ./MyGodotProject
godot-cli login
godot-cli setup-mcp claude-code ./MyGodotProject
godot-cli open ./MyGodotProject
```

그런 다음 에이전트에게 "Camera3D와 MeshInstance3D 큐브가 있는 Node3D 씬을 추가하고 Main.tscn으로 저장해줘"처럼 요청해 보세요. [시작하기](https://ai-game.dev/ko/docs/wiki/godot/getting-started) 페이지에서 같은 단계를 설명과 함께 따라가 볼 수 있고, 사이트의 [빠른 시작](https://ai-game.dev/ko/docs/quickstart)은 세 엔진 모두를 다룹니다.

## 이 위키의 페이지

- [설치](https://ai-game.dev/ko/docs/wiki/godot/installation): 모든 설치 경로(데스크톱 앱, `godot-cli`, Asset Library, 릴리스 zip)와 정확한 NuGet 패키지를 설명합니다.
- [시작하기](https://ai-game.dev/ko/docs/wiki/godot/getting-started): 첫 연결, 첫 프롬프트, 모든 것이 제대로 동작하는지 확인하는 방법입니다.
- [AI 클라이언트 연결](https://ai-game.dev/ko/docs/wiki/godot/connecting-ai-clients): 클라우드 엔드포인트와 자체 서버, 기기 로그인, 프로젝트 키, 각 에이전트용 `setup-mcp`를 다룹니다.
- [구성](https://ai-game.dev/ko/docs/wiki/godot/configuration): AI Game Developer 독, 저장된 설정, `GODOT_MCP_*` 환경 변수입니다.
- [도구](https://ai-game.dev/ko/docs/wiki/godot/tools): 내장 도구 계열, RQL, 각 도구의 용도입니다.
- [커스텀 도구](https://ai-game.dev/ko/docs/wiki/godot/custom-tools): C#로 직접 MCP 도구를 작성하고 실행 중인 게임에서 도구를 노출하는 방법입니다.
- [확장](https://ai-game.dev/ko/docs/wiki/godot/extensions): 애니메이션, CSG, 내비게이션, 타일맵 및 인기 Godot 애드온을 위한 선택적 패키지입니다.
- [godot-cli 레퍼런스](https://ai-game.dev/ko/docs/wiki/godot/cli): 모든 `godot-cli` 명령과 플래그입니다.
- [문제 해결](https://ai-game.dev/ko/docs/wiki/godot/troubleshooting): 애드온이 로드되지 않음, 에이전트에 도구가 보이지 않음, 리로드 문제입니다.
- [FAQ](https://ai-game.dev/ko/docs/wiki/godot/faq): 자주 묻는 질문에 대한 짧은 답변입니다.

## 사이트의 더 많은 내용

- [Godot MCP 설치](https://ai-game.dev/ko/engines/godot): Godot 설치 페이지입니다.
- [Godot 도구 카탈로그](https://ai-game.dev/docs/tools/godot)와 [Godot 확장](https://ai-game.dev/docs/extensions/godot).
- [Godot 모범 사례](https://ai-game.dev/docs/best-practices/godot): 효과적인 프롬프트 작성 방법입니다.
- [MCP 엔드포인트](https://ai-game.dev/ko/mcp-endpoint-info) 및 [인증](https://ai-game.dev/docs/auth): 호스팅 엔드포인트와 로그인 작동 방식입니다.
- [AI Game Dev 앱 위키](https://ai-game.dev/ko/docs/wiki/app), 그리고 [Unity MCP](https://ai-game.dev/ko/docs/wiki/unity)와 [Unreal MCP](https://ai-game.dev/ko/docs/wiki/unreal) 위키입니다.

- [**설치** AI Game Dev 앱, godot-cli, Godot Asset Library 또는 릴리스 zip으로 Godot MCP 애드온을 설치하고, .csproj에 맞는 정확한 NuGet 패키지를 확인하세요.](https://ai-game.dev/ko/docs/wiki/godot/installation)
- [**시작하기** Godot MCP를 클라우드에 연결하고 Claude Code 같은 AI 에이전트를 설정한 뒤, 연결을 확인하고 Godot 에디터에서 첫 AI 프롬프트를 실행하세요.](https://ai-game.dev/ko/docs/wiki/godot/getting-started)
- [**AI 클라이언트 연결** Claude Code, Cursor, Copilot, Codex, Gemini 등 MCP 클라이언트를 ai-game.dev 클라우드 엔드포인트나 자체 로컬 서버를 통해 Godot MCP에 연결하세요.](https://ai-game.dev/ko/docs/wiki/godot/connecting-ai-clients)
- [**구성** AI Game Developer dock에서 Godot MCP를 구성하고, AI 에이전트가 볼 도구를 선택하며, GODOT\_MCP\_\* 환경 변수로 설정을 재정의하세요.](https://ai-game.dev/ko/docs/wiki/godot/configuration)
- [**도구** AI 에이전트가 Godot 에디터에서 사용하는 Godot MCP 도구, 노드·씬·리소스용 RQL 쿼리, C# 및 GDScript 스크립트, 스크린샷과 인게임 도구입니다.](https://ai-game.dev/ko/docs/wiki/godot/tools)
- [**사용자 지정 도구** C#로 나만의 Godot MCP 도구를 작성하고, 메인 스레드에서 Godot API를 호출하며, 실행 중인 Godot 게임에서 도구와 프롬프트, 리소스를 노출하세요.](https://ai-game.dev/ko/docs/wiki/godot/custom-tools)
- [**확장** AnimationPlayer, CSG, GridMap, 내비게이션, 파티클, TileMapLayer, Beehave, Dialogic, Phantom Camera, Terrain3D용 선택적 Godot MCP 확장을 설치하세요.](https://ai-game.dev/ko/docs/wiki/godot/extensions)
- [**godot-cli 레퍼런스** install-plugin, login, setup-mcp부터 open, exec, run-tool, configure, install-extension까지 Godot MCP를 위한 모든 godot-cli 명령과 플래그를 정리합니다.](https://ai-game.dev/ko/docs/wiki/godot/cli)
- [**문제 해결** 애드온이 로드되거나 컴파일되지 않는 문제부터 빈 Extensions 목록, 도구 누락, 재로드 오류, .NET 10 크래시까지 Godot MCP의 흔한 문제를 해결합니다.](https://ai-game.dev/ko/docs/wiki/godot/troubleshooting)
- [**FAQ** Godot MCP, Godot 에디터용 AI 어시스턴트에 대한 짧은 답변: Godot 버전, GDScript 프로젝트, 오프라인 사용, 비용, 보안, 내보낸 게임.](https://ai-game.dev/ko/docs/wiki/godot/faq)

---

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

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