이 페이지는 영어에서 기계 번역되었습니다. 영어 원문 읽기.

도구

AI 에이전트가 Godot 에디터에서 사용하는 Godot MCP 도구, 노드·씬·리소스용 RQL 쿼리, C# 및 GDScript 스크립트, 스크린샷과 인게임 도구입니다.

2026년 11월 4일 업데이트 Markdown으로 보기

Godot MCP는 9개 계열에 걸쳐 24개의 기본 도구를 제공합니다. 대부분의 에디터 작업은 세 가지 RQL 도구를 통해 이루어지므로, 에이전트는 수십 개의 개별 도구 대신 노드, 씬, 리소스, 파일, 에디터 상태에 하나의 쿼리 언어를 사용합니다. 이 페이지는 각 계열과 에이전트가 이를 사용하는 시점을 설명합니다. 매개변수와 예시 프롬프트가 포함된 검색 가능한 목록은 Godot tools catalog에서 확인할 수 있습니다.

도구 계열

계열도구용도
rqlrql-query, rql-mutate, rql-schema실행 중인 에디터를 읽고 변경합니다: 노드, Godot 속성, 씬, 리소스, 파일, 프로젝트 설정, 입력 맵, 오토로드, 그룹, 시그널, 에디터 상태.
scriptscript-read, script-create, script-update, script-delete, script-attach-to-node, script-validate, script-build, script-executeC# 및 GDScript 파일, 스크립트 연결, GDScript 검증, C# 프로젝트 빌드, 에디터에서 C# 실행.
screenshotscreenshot-viewport, screenshot-camera, screenshot-isolated에디터 뷰포트, 카메라 또는 노드를 단독으로 렌더링한 PNG 이미지.
consoleconsole-get-logs, console-clear-logs실행 중인 게임의 로그. 에디터에서는 RQL console 소스를 사용합니다.
reflectionreflection-method-find, reflection-method-call실행 중인 게임에서 C# 메서드를 찾고 호출합니다. 에디터에서는 RQL call을 사용합니다.
runtime-errorsruntime-errors-get, runtime-errors-clear실행 중인 게임 내부에서 발생한 오류. 기본적으로 꺼져 있습니다.
pingping준비 상태 확인 프로브. 시스템 도구로, 에이전트에게 표시되지 않습니다.
skillsgodot-skill-create, godot-skill-generate새 도구 파일을 작성하고 스킬 파일을 다시 생성합니다. 시스템 도구입니다.
sessionsession-closegodot-cli가 시작한 에디터를 저장하고 종료합니다. 시스템 도구입니다.

시스템 도구는 서버의 /api/system-tools/ 경로를 통해 접근하며(예: godot-cli run-system-tool ping), AI 에이전트에게는 나열되지 않습니다. console, reflection, runtime-errors 계열은 직접 연결한 실행 중인 게임을 대상으로 합니다. 자세한 내용은 Custom tools를 참고하세요.

RQL: 에디터를 위한 단일 쿼리 언어

RQL(Reflection Query Language)은 에디터 도구의 데이터 계층입니다. 쿼리는 소스에서 시작하고, |로 구분된 단계로 필터링하고 형태를 지정하며, rql-mutate에서는 set 또는 call로 끝납니다. 에이전트가 보낼 수 있는 몇 가지 예시는 다음과 같습니다:

nodes | where class == "OmniLight3D" | select name props["light_energy"]
nodes | where name starts-with "Enemy" | set Visible = false
root | call AddChild("Node3D", "Props")
project | call AddInputAction("jump", ["Key:Space"])
files | sort size desc | first 5 | select path size importedSize
editor | call SaveScene()
  • rql-query는 읽기 전용이며 간결한 행을 반환합니다.
  • rql-mutate는 변경을 수행합니다. 모든 대상과 값이 먼저 검사되므로 실패한 쿼리는 아무것도 변경하지 않습니다. dry_run은 변경 사항을 미리 보여줍니다. 각 호출은 하나의 실행 취소 단계입니다(에디터에서 Ctrl+Z).
  • rql-schema는 소스, 함수, 편집 중인 씬의 노드 클래스를 나열하거나, 한 타입의 멤버, 메서드, Godot 속성을 나열합니다. 확장 이름을 지정하면 해당 확장의 가이드를 출력합니다.

소스에는 nodes, root, selection, scenes, files, folders, classes, console, editor, project, settings, inputActions, autoloads, groups, layers, tools가 있습니다. Godot 속성은 C# 멤버(Position, Visible)로 접근하거나 props["snake_name"]에 Godot 이름으로 접근할 수 있으며, 여기에는 GDScript 변수도 포함됩니다. RQL은 시그널, 그룹, TileSet, Theme, ShaderMaterial 매개변수, MeshLibrary도 다룹니다.

에디터 호출은 씬과 파일 작업을 다룹니다: NewScene, OpenScene, SaveScene, SaveAllScenes, ReloadScene, CreateResource, MoveResource, DeleteResource, CreateFolder, DeleteFolder, Reimport, Undo, Redo, PlayScene, StopScene. gameLog 소스는 에디터에서 시작한 게임이 출력한 내용을 읽습니다.

씬 편집은 직접 편집한 것처럼 씬을 저장되지 않은 상태로 표시합니다. 편집된 리소스 파일과 project.godot은 즉시 저장됩니다.

스크립트: C# 및 GDScript

  • script-read, script-create, script-update, script-delete는 .cs 및 .gd 파일에서 작동합니다.
  • script-attach-to-node는 노드에 스크립트를 연결합니다.
  • script-validate는 GDScript 파일의 파싱 및 컴파일 진단을 반환합니다. 경로를 지정하지 않으면 res:// 아래의 모든 .gd 파일을 검사합니다.
  • script-build는 새 C# 스크립트가 로드되도록 dotnet build(Debug)를 실행합니다. 그러면 Godot가 C# 어셈블리를 다시 로드하고 애드온이 재연결되며, 빌드 결과(경고 또는 오류)는 재로드 후에 도착합니다.
  • script-execute는 Roslyn으로 에디터에서 C#을 컴파일하고 실행합니다. 일반적인 문장을 작성하면 마지막 식이 결과가 됩니다. 값과 코드가 출력한 내용을 반환합니다. 스니펫은 기본적으로 30초 후에 시간 초과되며(최대 4분), 무한 루프는 에디터를 멈추게 하는 대신 시간 초과 오류를 반환합니다.

터미널에서도 script-execute를 호출할 수 있습니다:

godot-cli exec 'EditorInterface.Singleton.GetEditedSceneRoot()?.Name' --path ./MyGodotProject

스크린샷

스크린샷 도구는 모델이 확인할 수 있는 PNG 이미지를 반환합니다: screenshot-viewport는 에디터 뷰포트를 캡처하고, screenshot-camera는 카메라 노드에서 렌더링하며, screenshot-isolated는 선택한 각도에서 노드 하나만 단독으로 렌더링합니다. 시각적인 변경 후에는 스크린샷을 요청해서 에이전트가 자신의 작업을 확인할 수 있게 하세요.

게임 내 도구

console-*, reflection-*, runtime-errors-*는 에디터가 아니라 게임 안에서 실행됩니다. 코드에서 옵트인하여 연결하기 전까지 게임은 아무것도 노출하지 않으며, runtime-errors-get은 추가로 WithRuntimeErrorCapture()가 필요합니다. GDScript 런타임 오류, push_error 및 push_warning, 셰이더 오류(Godot 4.5 이상), 처리되지 않은 C# 예외를 캡처하므로 에이전트가 게임을 실행해 실제로 무엇이 깨졌는지 확인할 수 있습니다. 설정: 사용자 정의 도구.

에이전트가 볼 도구 선택하기

모든 도구에는 도크(MCP features, Tools, Open)와 godot-cli configure에 Visible 스위치가 있습니다. 도구를 숨기면 에이전트의 도구 목록에서 제거되어 컨텍스트를 절약하지만, 차단되지는 않습니다. 구성을 참고하세요.

더 많은 도구

  • 확장은 RQL이 AnimationPlayer, CSG, GridMap, 내비게이션, 파티클, TileMapLayer와 Beehave, Dialogic, Phantom Camera, Terrain3D 애드온을 다룰 수 있게 해줍니다.
  • 사용자 정의 도구는 C#으로 나만의 도구를 작성하는 방법을 보여줍니다.
  • Godot 모범 사례에는 이러한 도구를 잘 활용하는 프롬프트 패턴이 있습니다.