시작하기

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

1단계: 프로젝트 열기#

CLI로 프로젝트를 여세요:

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 앱에 사용됩니다. 세션은 계정의 연결된 기기에 표시되며, 거기서 해지할 수 있습니다. 자세한 내용: 인증.

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

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

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

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

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

4단계: 연결 확인#

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

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 모범 사례에 있습니다.

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

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

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

클라우드를 사용하는 대신 MCP 서버를 직접 자신의 컴퓨터에서 실행할 수 있습니다. 독에서 모드를 Custom으로 전환하고 Start Server를 클릭하세요. 그러면 애드온이 GitHub에서 해당 서버 빌드를 다운로드해 실행하고 연결합니다. 그다음 에이전트가 로컬 URL을 가리키도록 설정하세요. 자세한 내용은 AI 클라이언트 연결하기를 참고하세요.

다음 단계#

• Configuration: 독, 로그 레벨, 에이전트가 볼 수 있는 도구를 설정합니다.
• Extensions: AnimationPlayer, CSG, 내비게이션, 타일맵 및 애드온 지원을 추가합니다.
• Troubleshooting: 위 단계가 작동하지 않았을 때 확인하세요.