godot-cli 레퍼런스

godot-cli는 npm에 게시된 Godot MCP용 명령줄 도구입니다. 애드온을 설치하고, 로그인하고, AI 에이전트 설정을 작성하며, 올바른 연결 설정으로 에디터를 빌드해 열고, 스크립트에서 도구를 호출합니다. 이 페이지는 godot-cli 0.34.0의 모든 명령과 해당 플래그를 나열합니다.

설치 및 기본 사항#

npm install -g godot-cli
godot-cli --help
godot-cli <command> --help

Node.js ^20.19.0 또는 >=22.12.0이 필요하며 Windows, macOS, Linux에서 동작합니다. 설치 없이도 모든 명령을 실행할 수 있습니다: npx godot-cli <command>.

대부분의 명령은 선택적 위치 인자 [path](또는 --path <path>)로 프로젝트 폴더를 받으며 기본값은 현재 폴더입니다. 모든 명령은 진단 출력을 위한 -v / --verbose를 지원합니다.

명령 개요#

install-plugin#

godot_mcp 애드온을 처음부터 끝까지 설치합니다: GitHub에서 애드온 릴리스를 다운로드하거나(또는 로컬 사본을 복사), .csproj에 NuGet PackageReference와 확장 카탈로그 <EmbeddedResource>를 추가하고, EnableDynamicLoading을 설정하며, project.godot에서 플러그인을 활성화합니다. 다시 실행해도 안전합니다.

godot-cli install-plugin ./MyGodotProject
godot-cli install-plugin --version 0.34.0 ./MyGodotProject
godot-cli install-plugin --source ./Godot-MCP/addons/godot_mcp ./MyGodotProject

install-extension#

godot-cli install-extension <id> [path]는 확장 카탈로그에서 id(패키지 id 또는 이름)를 확인해 해당 <PackageReference>를 추가하거나 업데이트합니다. --version <x.y.z>는 최신 안정 버전 대신 정확한 버전을 요청합니다. 이후 godot-cli build를 실행하세요. Extensions를 참고하세요.

remove-plugin#

project.godot의 [editor_plugins] 섹션에서 애드온을 비활성화합니다. addons/godot_mcp/나 .csproj 항목은 삭제하지 않습니다.

create-project#

최소한의 Godot 4 프로젝트(project.godot와 icon.svg)를 생성합니다. 기존 Godot, Unity 또는 Unreal 프로젝트를 덮어쓰지 않습니다.

build#

애드온이 다음 에디터 실행 시 로드되도록 프로젝트의 .csproj에 dotnet build를 실행합니다. .csproj가 없는 프로젝트는 건너뜁니다.

open#

C# 어셈블리를 빌드하고 Godot 에디터를 찾아 프로젝트를 엽니다. 빌드가 실패하면 에디터는 시작되지 않습니다. 에디터 탐색 순서는 --editor-path, GODOT_BIN 또는 GODOT4_BIN 환경 변수, PATH의 Godot 바이너리(Windows에서는 .NET 빌드 우선), 일반적인 설치 폴더 순입니다.

close#

프로젝트에서 실행 중인 Godot 에디터를 정상적으로 종료합니다.

exec#

script-execute 도구로 프로젝트의 에디터에서 C#을 실행합니다. 코드는 일반 문장으로 구성되며, 마지막 식이 결과입니다. 프로젝트의 에디터가 실행 중이면 이를 재사용합니다(사용자의 에디터가 Custom 모드이고 로컬 서버가 시작되어 있어야 함). 그렇지 않으면 exec는 프로젝트를 빌드하고 로컬 서버에 연결된 헤드리스 에디터를 시작하며, 이 에디터는 호출 없이 --idle초가 지나면 종료됩니다(기본값 300).

godot-cli exec '1 + 2' --path ./MyGodotProject
godot-cli exec -f snippet.cs --using MyGame.Gameplay
godot-cli exec 'Helper.Twice(21)' --include helpers

컴파일 오류는 스니펫의 해당 줄을 가리키며 코드 1로 종료됩니다.

login#

OAuth 2.1 디바이스 플로로 ai-game.dev에 로그인하고 자격 증명을 ~/.ai-game-dev/credentials.json에 저장하면 에디터가 이를 인식합니다. Connecting AI clients를 참고하세요.

setup-mcp#

godot-cli setup-mcp <agent> [path]는 에이전트의 MCP 구성을 작성하며, 기본적으로 이 프로젝트에 고정됩니다. 에이전트 id와 구성 파일은 Connecting AI clients에 나열되어 있습니다.

setup-skills#

godot-cli setup-skills <agent> [path]는 애드온의 도구 패밀리에 대한 SKILL.md 파일을 에이전트의 스킬 폴더(예: .claude/skills)에 작성합니다. 실행 중인 에디터는 필요하지 않습니다. --list는 각 에이전트의 스킬 지원 여부를 보여줍니다.

configure#

MCP 클라이언트가 보는 도구, 프롬프트, 리소스를 .godot-mcp/features.json에서 나열하거나 변경합니다. 숨겨진 항목도 이름으로 호출하면 여전히 실행됩니다.

run-tool과 run-system-tool#

서버의 HTTP API를 통해 도구를 직접 호출합니다. run-tool은 /api/tools/<tool>로, run-system-tool은 /api/system-tools/<tool>로 POST합니다(MCP 클라이언트에서 숨겨진 도구, 예: ping).

godot-cli run-tool rql-query ./MyGodotProject --input '{"query":"nodes | select name class"}'
godot-cli run-system-tool ping ./MyGodotProject

--url이 없으면 서버는 GODOT_MCP_HOST, 그다음 GODOT_MCP_CLOUD_URL, 그다음 GODOT_MCP_CONNECTION_MODE=Cloud일 때 클라우드, 그다음 프로젝트에 등록된 서버, 마지막으로 프로젝트의 로컬 포트 순으로 선택됩니다.

status와 wait-for-ready#

status는 프로젝트에서 실행 중인 에디터를 감지하고 서버를 프로브합니다(--url, --token, --timeout <ms>, 기본값 5000). wait-for-ready는 에디터가 응답할 때까지 ping을 폴링합니다(--url, --token, --timeout <ms> 기본값 120000, --interval <ms> 기본값 3000). open 뒤에 스크립트에서 사용하세요.

update#

godot-cli update는 npm에서 더 새로운 godot-cli를 확인해 설치하며, --check는 보고만 합니다.

관련 항목#

• AI Game Dev 앱에는 자체 gamedev CLI가 있습니다: App CLI.
• Unity와 Unreal에는 unity-mcp-cli와 unreal-mcp-cli가 있습니다: Unity MCP와 Unreal MCP 위키를 참고하세요.