# 시작하기 — Godot · AI Game Developer Wiki

Godot MCP를 클라우드에 연결하고 Claude Code 같은 AI 에이전트를 설정한 뒤, 연결을 확인하고 Godot 에디터에서 첫 AI 프롬프트를 실행하세요.

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

이 페이지는 애드온이 설치된 상태에서 Godot 씬을 편집하는 AI 에이전트를 구성하는 것까지 안내합니다. 애드온이 이미 프로젝트에 있다고 가정하며, 없다면 [설치](https://ai-game.dev/ko/docs/wiki/godot/installation)부터 시작하세요. 각 단계는 기본 Cloud 모드를 사용하며, 이 모드에서는 에디터와 에이전트가 모두 [ai-game.dev](https://ai-game.dev)에 연결되고 한 번만 로그인하면 됩니다.

## 1단계: 프로젝트 열기

CLI로 프로젝트를 여세요:

```bash
godot-cli open ./MyGodotProject
```

`open`은 먼저 C# 어셈블리를 빌드한 다음 에디터를 시작합니다. 이 빌드는 첫 실행에서 특히 중요합니다. Godot은 활성화된 애드온을 즉시 로드하는데, 빌드된 어셈블리가 없으면 `GodotMcpPlugin.cs`를 로드할 수 없다고 보고하고 애드온을 비활성화합니다. 대신 Godot 프로젝트 관리자에서 프로젝트를 여는 경우에는 한 번 빌드하고(에디터의 Build 버튼 또는 `godot-cli build`), Godot이 플러그인을 껐다면 다시 활성화하세요.

애드온이 로드되면 에디터의 Output 패널에 `[Godot-MCP] plugin loaded`가 출력되고, **AI Game Developer** 독이 오른쪽 위 독 영역에 나타납니다.

## 2단계: 로그인

Cloud 모드에는 ai-game.dev 계정이 필요합니다. 다음 중 하나를 선택하세요:

- 독에서 모드를 **Cloud**로 유지하고 **Authorize**를 클릭하세요. 짧은 코드와 함께 브라우저가 열리면 ai-game.dev 계정으로 승인하세요.
- 터미널에서 `godot-cli login`을 실행하세요. 동일한 OAuth 디바이스 흐름을 사용하며 자격 증명을 `~/.ai-game-dev/credentials.json`에 저장하고, 에디터가 이를 자동으로 인식합니다.

로그인은 컴퓨터당 한 번만 하면 됩니다. 동일한 자격 증명이 Godot MCP, Unity MCP, Unreal MCP, 엔진 CLI 및 AI Game Dev 앱에 사용됩니다. 세션은 계정의 연결된 기기에 표시되며, 거기서 해지할 수 있습니다. 자세한 내용: [인증](https://ai-game.dev/docs/auth).

## 3단계: AI 에이전트 연결

사용하는 에이전트에 대한 MCP 설정을 작성하세요. Claude Code의 경우:

```bash
godot-cli setup-mcp claude-code ./MyGodotProject
```

이 명령은 이 프로젝트에 고정된 URL과 함께 프로젝트에 `.mcp.json`을 작성하므로, 에디터를 여러 개 열어 두어도 에이전트가 이 에디터에 접근합니다. 독에서도 동일하게 할 수 있습니다. **AI agent** 섹션에서 에이전트를 선택하고 **Configure**를 클릭하세요. 다른 에이전트(Cursor, VS Code Copilot, Codex, Gemini 등)는 [AI 클라이언트 연결](https://ai-game.dev/ko/docs/wiki/godot/connecting-ai-clients)에 나열되어 있습니다.

설정을 작성한 후에는 에이전트를 재시작하거나 MCP 서버를 다시 로드하세요. 설정 파일이 프로젝트 폴더에 있다면 해당 폴더에서 에이전트를 시작하세요(Claude Code는 시작한 폴더의 `.mcp.json`을 읽습니다).

## 4단계: 연결 확인

독의 **Connection** 섹션에는 Godot, MCP 서버, AI 에이전트의 세 지점이 한 줄로 표시됩니다. 에디터가 연결되고 에이전트 세션이 활성화되면 세 지점이 모두 켜지고, 에이전트 행에 클라이언트 이름이 표시됩니다. 터미널에서 에디터가 응답할 때까지 기다릴 수도 있습니다:

```bash
godot-cli wait-for-ready ./MyGodotProject
godot-cli status ./MyGodotProject
```

`wait-for-ready`는 준비 상태 프로브(`ping`)에 응답이 있을 때까지 폴링하며, 기본 제한 시간은 최대 2분입니다. `status`는 프로젝트에 대해 에디터가 실행 중인지와 서버가 응답하는지를 보고합니다.

에이전트에게 도구 목록을 요청하거나 Claude Code에서 `/mcp`를 실행하세요. `rql-query`, `rql-mutate`, `script-create`, `screenshot-viewport` 같은 도구가 보여야 합니다.

## 5단계: 첫 프롬프트

에이전트 채팅에서 다음을 시도해 보세요. 각 요청은 실제 도구로 이어지므로 에디터에서 씬이 바뀌는 것을 볼 수 있습니다:

- "Camera3D와 MeshInstance3D 큐브가 있는 Node3D 씬을 추가하고 Main.tscn으로 저장해 줘."
- "반지름 2인 원 모양으로 큐브 3개를 만들어 줘."
- "씬에 있는 모든 OmniLight3D를 energy 값과 함께 나열해 줘."
- "바닥용 StandardMaterial3D를 만들고 albedo 색상을 회색으로 설정해 줘."
- "public float Speed를 가진 Player.cs 스크립트를 만들고 Player 노드에 붙인 다음 프로젝트를 빌드해 줘."
- "Space 키에 jump라는 입력 액션을 추가해 줘."
- "뷰포트 스크린샷을 찍고 무엇이 보이는지 알려 줘."

에이전트가 수행한 씬 편집은 실행 취소할 수 있습니다. 에디터에서 Ctrl+Z를 눌러 되돌리면 직접 편집한 것과 똑같이 동작합니다. 씬 변경은 씬을 저장되지 않은 상태로 표시하므로 에이전트에게 저장을 요청하거나 직접 저장하세요. 더 많은 프롬프트 예시는 [Godot 모범 사례](https://ai-game.dev/docs/best-practices/godot)에 있습니다.

## 에이전트가 볼 수 있는 것과 없는 것

에이전트는 애드온이 노출하는 도구를 통해 작업합니다. 씬 트리, Godot 속성(GDScript 변수 포함), 리소스, 파일, 프로젝트 설정, 입력 맵, 오토로드, 콘솔, 에디터 상태를 RQL을 통해 읽을 수 있고 스크린샷도 볼 수 있습니다. 에디터 UI를 클릭할 수는 없습니다. 전체 목록은 [Tools](https://ai-game.dev/ko/docs/wiki/godot/tools)와 [Godot tools catalog](https://ai-game.dev/docs/tools/godot)에 있습니다.

## 오프라인으로 사용하는 편이 좋으신가요?

클라우드를 사용하는 대신 MCP 서버를 직접 자신의 컴퓨터에서 실행할 수 있습니다. 독에서 모드를 **Custom**으로 전환하고 **Start Server**를 클릭하세요. 그러면 애드온이 GitHub에서 해당 서버 빌드를 다운로드해 실행하고 연결합니다. 그다음 에이전트가 로컬 URL을 가리키도록 설정하세요. 자세한 내용은 [AI 클라이언트 연결하기](https://ai-game.dev/ko/docs/wiki/godot/connecting-ai-clients#custom-mode)를 참고하세요.

## 다음 단계

- [Configuration](https://ai-game.dev/ko/docs/wiki/godot/configuration): 독, 로그 레벨, 에이전트가 볼 수 있는 도구를 설정합니다.
- [Extensions](https://ai-game.dev/ko/docs/wiki/godot/extensions): AnimationPlayer, CSG, 내비게이션, 타일맵 및 애드온 지원을 추가합니다.
- [Troubleshooting](https://ai-game.dev/ko/docs/wiki/godot/troubleshooting): 위 단계가 작동하지 않았을 때 확인하세요.

---

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

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