godot-mcp

AI 어시스턴트에게 Godot 게임 엔진에 대한 **완전한 제어권 (full control)**을 부여하는 포괄적인 Model Context Protocol (MCP) 서버입니다. 네트워킹, 3D/2D 렌더링, UI 컨트롤, 오디오 효과, 애니메이션 트리 (animation trees), 파일 I/O, 런타임 코드 실행 (runtime code execution), 속성 검사 (property inspection), 씬 조작 (scene manipulation), 시그널 관리 (signal management), 물리 (physics), 프로젝트 생성 등을 아우르는 **149개의 도구 (tools)**를 제공합니다.

이 프로젝트는 Solomon Elias (Coding-Solo)의 godot-mcp를 기반으로 구축되었으며 이를 확장한 것입니다. 원본 프로젝트는 TypeScript MCP 서버, 헤드리스 (headless) GDScript 운영 시스템, TCP 기반 런타임 상호작용 서버를 포함한 기초 아키텍처를 제공했습니다. 귀하의 훌륭한 오픈 소스 작업 덕분에 이것이 가능해졌음에 감사드립니다!

새로운 기능 (원본 대비 개선 사항)

원본 godot-mcp는 기본적인 프로젝트 관리 및 씬 생성을 위한 20개의 도구를 제공했습니다. 이 포크(fork) 버전은 다음과 같은 주요 추가 사항을 통해 이를 149개의 도구로 확장했습니다:

game_eval

실행 중인 게임에서 반환 값을 포함한 임의의 GDScript 코드를 실행
비동기 (async) GDScript 코드에 대한 완전한 await 지원
게임이 일시 정지된 상태에서도 작동 (PROCESS_MODE_ALWAYS)

런타임 노드 검사 및 조작 (Runtime Node Inspection & Manipulation)

game_get_property / game_set_property

경로를 통해 모든 노드의 모든 속성을 읽기/쓰기
game_call_method
인수를 사용하여 모든 노드의 모든 메서드를 호출
game_get_node_info
완전한 노드 자기 성찰 (introspection): 속성 (properties), 시그널 (signals), 메서드 (methods), 자식 노드 (children)
game_instantiate_scene
실행 중인 게임에 동적으로 씬 추가
game_remove_node
런타임에 노드 제거
game_change_scene
런타임에 씬 전환
game_reparent_node
부모 노드 간에 노드 이동

game_connect_signal

런타임에 시그널 연결 설정
game_disconnect_signal
시그널 연결 제거
game_emit_signal
인수를 사용하여 시그널 발생 (emit)

game_play_animation

AnimationPlayer 제어 (재생, 정지, 일시 정지, 목록 확인)
game_tween_property
설정 가능한 이징 (easing)을 통한 부드러운 속성 애니메이션

game_pause

게임 일시 정지/재개
game_performance
FPS, 프레임 타임 (frame time), 메모리 (memory), 오브젝트 개수 (object counts), 드로우 콜 (draw calls)
game_wait
N 프레임 대기 (타이밍에 민감한 작업)
game_get_nodes_in_group
그룹별 노드 쿼리 (Query)
game_find_nodes_by_class
특정 클래스의 모든 노드 찾기

헤드리스 씬 작업 (Headless Scene Operations, 실행 중인 게임 불필요)

read_scene

모든 .tscn 파일을 파싱하여 속성이 포함된 전체 노드 트리를 JSON으로 가져오기
modify_scene_node
씬 파일 내 노드 속성 변경
remove_scene_node
씬 파일에서 노드 제거
attach_script
씬 내 노드에 GDScript 파일 부착
create_resource
.tres 리소스 파일 생성 (재질 (materials), 테마 (themes) 등)

read_project_settings

project.godot를 구조화된 JSON으로 파싱
modify_project_settings
프로그래밍 방식으로 프로젝트 설정 변경
list_project_files
확장자별 프로젝트 파일 목록 나열 및 필터링

read_file

/ write_file

/ delete_file

Godot 프로젝트 내 전체 파일 시스템 접근
create_directory
스크립트, 씬, 에셋을 위한 디렉토리 구조 생성

game_get_errors

마지막 호출 이후의 새로운 push_error/push_warning 메시지 가져오기
game_get_logs
마지막 호출 이후 실행 중인 게임으로부터의 새로운 print 출력 가져오기

game_key_hold

/ game_key_release

이동 테스트를 위한 키 누르기 (WASD 등)
game_scroll
마우스 스크롤 휠 이벤트
game_mouse_drag
여러 프레임에 걸쳐 두 지점 사이를 드래그
game_gamepad
게임패드 버튼 및 축 (axis) 입력 이벤트

프로젝트 생성 및 구성

create_project

처음부터 새로운 Godot 프로젝트 생성
manage_autoloads
오토로드 (autoloads) 추가, 제거 또는 목록 나열
manage_input_map
입력 액션 (input actions) 및 키 바인딩 추가, 제거 또는 목록 나열
manage_export_presets
내보내기 프리셋 (export preset) 구성 생성 또는 수정

game_get_camera

/ game_set_camera

2D/3D 카메라 쿼리 및 제어
game_raycast
물리 레이캐스트 (physics rays) 발사 (2D와 3D 자동 감지)
game_get_audio
오디오 버스 레이아웃 및 재생 중인 스트림 가져오기
game_spawn_node
런타임에 속성을 포함한 모든 노드 타입 생성
game_set_shader_param
머티리얼 (Materials)에 셰이더 파라미터 (Shader parameters) 설정
game_audio_play

/ game_audio_bus

전체 오디오 재생 및 버스 (Bus) 제어
game_navigate_path
내비게이션 경로 (Navigation paths) 쿼리 (2D/3D)
game_tilemap
타일맵 레이어 (TileMapLayer) 셀 (Cells) 가져오기/설정하기
game_add_collision
물리 바디 (Physics bodies)에 충돌 모양 (Collision shapes) 추가
game_environment
포스트 프로세싱 (Post-processing) 구성 (안개, 글로우, SSAO, 톤맵 등)
game_manage_group
그룹 (Groups)에서 노드 추가/제거
game_create_timer
프로그래밍 방식으로 타이머 (Timer) 노드 생성
game_set_particles
GPUParticles2D/3D 속성 및 프로세스 머티리얼 (Process materials) 구성
game_create_animation
값/메서드/베지에/오디오 트랙 (Tracks) 및 키프레임 (Keyframes)을 포함한 애니메이션 생성
export_project
헤드리스 (Headless) 프로젝트 내보내기 빌드 트리거 (CI/CD 준비 완료)
game_serialize_state
전체 노드 트리 상태를 JSON으로 저장/로드
game_physics_body
질량 (Mass), 속도 (Velocity), 댐핑 (Damping), 마찰 (Friction), 탄성 (Bounce) 구성
game_create_joint
물리 조인트 (Physics joints) 생성 (핀, 스프링, 힌지, 콘, 슬라이더)
game_bone_pose
캐릭터 애니메이션을 위한 스켈레톤 본 포즈 (Skeleton bone poses) 가져오기/설정하기
game_ui_theme
색상, 상수 (Constant), 폰트 크기 테마 오버라이드 (Theme overrides) 적용
game_viewport
서브 뷰포트 (SubViewport) 노드 생성/구성
game_debug_draw
디버그 지오메트리 (Debug geometry) 그리기 (선, 구, 상자)

game_http_request

헤더 및 바디를 포함한 HTTP GET/POST/PUT/DELETE
game_websocket
WebSocket 클라이언트 연결/해제/메시지 전송
game_multiplayer
ENet 멀티플레이어 서버/클라이언트 생성/해제
game_rpc
노드에서 RPC 메서드 호출 또는 구성

game_script

런타임에 노드 스크립트 부착, 분리 또는 소스 가져오기
game_window
창 크기, 전체 화면, 제목, 위치 가져오기/설정하기
game_os_info
플랫폼, 로케일 (Locale), 화면, 어댑터, 메모리 정보 가져오기
game_time_scale
Engine.time_scale 및 타이밍 정보 가져오기/설정하기
game_process_mode
노드 프로세스 모드 (일시정지 가능/항상/비활성화) 설정
game_world_settings
중력, 물리 FPS 및 월드 설정 가져오기/설정하기

game_list_signals

연결 정보를 포함하여 노드의 모든 시그널 (Signals) 목록 나열
game_await_signal
타임아웃과 함께 시그널 (Signal)을 대기하고 인자 (Args) 반환
game_touch
터치 누름/떼기/드래그 및 제스처 (Gestures) 시뮬레이션
game_input_state
눌린 키, 마우스 위치, 연결된 패드 (Pads) 쿼리
game_input_action
런타임 입력 맵 (InputMap) 액션 및 강도 (Strength) 관리

game_csg

불리언 연산 (Boolean operations)을 사용하는 CSG 노드 생성/설정
game_multimesh
인스턴싱 (Instancing)을 위한 MultiMeshInstance3D 생성/설정
game_procedural_mesh
정점 데이터 (Vertex data)로부터 ArrayMesh를 통해 메시 (Mesh) 생성
game_light_3d
3D 조명 (Directional/Omni/Spot) 생성/설정
game_mesh_instance
프리미티브 메시 (Primitive meshes)를 사용한 MeshInstance3D 생성
game_gridmap
GridMap 셀 설정/가져오기/삭제 및 사용된 셀 쿼리
game_3d_effects
ReflectionProbe, Decal 또는 FogVolume 생성
game_gi
VoxelGI 또는 LightmapGI 생성/설정
game_path_3d
Path3D/Curve3D 생성 및 커브 포인트 (Curve points) 관리
game_sky
절차적/물리적 스카이 (Sky)를 사용하는 Sky 생성/설정
game_camera_attributes
카메라의 피사체 심도 (DOF), 노출 (Exposure), 자동 노출 (Auto-exposure) 설정
game_navigation_3d
NavigationRegion3D 생성/설정 및 베이크 (Bake)
game_physics_3d
Area3D 쿼리 및 점/도형 교차 테스트 (Intersection tests)

game_canvas

CanvasLayer 및 CanvasModulate 생성/설정
game_canvas_draw
2D 드로잉: 선/사각형/원/다각형/텍스트/지우기
game_light_2d
2D 조명 및 라이트 오클루더 (Light occluders) 생성/설정
game_parallax
ParallaxBackground 및 레이어 생성/설정
game_shape_2d
Line2D/Polygon2D 포인트 조작
game_path_2d
Path2D/Curve2D 관리 및 AnimatedSprite2D
game_physics_2d
Area2D 쿼리 및 2D 점/도형 교차

game_animation_tree

AnimationTree 상태 머신 (State machine) 이동 및 파라미터 (Params)
game_animation_control
AnimationPlayer 탐색 (Seek)/큐 (Queue)/속도/정보 제어
game_skeleton_ik
SkeletonIK3D 시작/중지/대상 위치 (Target position) 설정

game_audio_effect

오디오 버스 이펙트 (Audio bus effects) 추가/제거/설정
game_audio_bus_layout
오디오 버스 생성/제거/재정렬 및 라우팅 (Routing)
game_audio_spatial
AudioStreamPlayer3D의 공간 속성 (spatial properties) 설정

rename_file

프로젝트 내 파일 이름 변경 또는 이동
manage_resource
.tres/.res 리소스 파일 읽기 또는 수정
create_script
템플릿으로부터 GDScript 파일 생성
manage_scene_signals
.tscn 파일 내 시그널 (signal) 연결 목록화/추가/제거
manage_layers
프로젝트 내 명명된 레이어 (layer) 정의 목록화/설정
manage_plugins
에디터 플러그인 (editor plugins) 목록화/활성화/비활성화
manage_shader
.gdshader 파일 생성 또는 읽기
manage_theme_resource
테마 (Theme) .tres 리소스 생성/읽기/수정
set_main_scene
project.godot에서 메인 씬 (main scene) 설정
manage_scene_structure
.tscn 씬 내 노드 (node) 이름 변경/복제/이동
manage_translations
프로젝트 내 번역 (translation) 파일 목록화/추가/제거
game_locale
런타임 (runtime) 시 로케일 (locale) 설정/가져오기 및 문자열 번역

game_ui_control

Control 노드에 포커스 (focus), 앵커 (anchors), 툴팁 (tooltip), 마우스 필터 (mouse filter) 설정
game_ui_text
LineEdit/TextEdit/RichTextLabel 텍스트 작업
game_ui_popup
Popup/Dialog/Window 노드 표시/숨기기/팝업
game_ui_tree
Tree 컨트롤: 아이템 가져오기/선택/접기/추가/제거
game_ui_item_list
ItemList/OptionButton: 아이템 가져오기/선택/추가/제거
game_ui_tabs
TabContainer/TabBar: 현재 탭 가져오기/설정
game_ui_menu
PopupMenu/MenuBar: 메뉴 아이템 추가/제거/가져오기
game_ui_range
ProgressBar/Slider/SpinBox/ColorPicker 가져오기/설정

game_render_settings

MSAA, FXAA, TAA, 스케일링 모드 (scaling mode)/스케일 (scale) 가져오기/설정
game_resource
런타임 리소스 로드, 저장 또는 프리로드 (preload)

재진입 방지 (Reentrancy guard) - 비동기 작업 (async operations) 중 명령이 동시에 처리되는 것을 방지
전체 타입 변환 (Full type conversion) - Vector2/3, Color, Quaternion, Basis, Transform2D/3D, AABB, Rect2 및 모든 Packed Array 타입을 지원
스마트 속성 타입 감지 (Smart property type detection) - 자동 타입 변환을 위해 노드의 get_property_list() 사용
PackedArray 직렬화 (PackedArray serialization) - 문자열 폴백 (fallback) 대신 적절한 JSON 배열 사용
유연한 에러 처리 (Graceful error handling) - 의존성 누락 시 씬 읽기를 원본 .tscn 텍스트로 폴백

프로젝트 관리 (7개 도구)

도구 (Tool)	설명 (Description)
`launch_editor`	프로젝트를 위한 Godot 에디터(editor) 실행
`run_project`	Godot 프로젝트를 실행하고 출력(output) 캡처
`stop_project`	실행 중인 프로젝트 중지
`get_debug_output`	콘솔 출력 및 에러(errors) 가져오기
`get_godot_version`	설치된 Godot 버전 가져오기
`list_projects`	디렉토리 내의 Godot 프로젝트 찾기
`get_project_info`	프로젝트 메타데이터(metadata) 가져오기

씬 관리 (Scene Management) (7개 도구)

도구 (Tool)	설명 (Description)
`create_scene`	루트 노드(root node) 타입과 함께 새 씬(scene) 생성
`add_node`	기존 씬에 노드(node) 추가
`load_sprite`	Sprite2D 노드에 텍스처(texture) 로드
`export_mesh_library`	씬을 MeshLibrary로 내보내기 (export)
`save_scene`	씬 저장 (선택적 변형 경로 포함)
`get_uid`	파일의 UID 가져오기 (Godot 4.4+)
`update_project_uids`	UID 업데이트를 위해 리소스(resources) 재저장

헤드리스 씬 작업 (Headless Scene Operations) (5개 도구)

도구 (Tool)	설명 (Description)
`read_scene`	전체 씬 트리(scene tree)를 JSON으로 읽기
`modify_scene_node`	씬 파일 내의 노드 속성(properties) 수정
`remove_scene_node`	씬 파일에서 노드 제거
`attach_script`	씬 노드에 GDScript 부착
`create_resource`	.tres 리소스(resource) 파일 생성

프로젝트 설정 (Project Settings) (3개 도구)

도구 (Tool)	설명 (Description)
`read_project_settings`	project.godot을 JSON으로 파싱 (parse)
`modify_project_settings`	프로젝트 설정 변경
`list_project_files`	프로젝트 파일 목록 표시 및 필터링

도구 (Tool)	설명 (Description)
`game_screenshot`	스크린샷 캡처 (base64 PNG)
`game_click`	특정 위치 클릭
`game_key_press`	키 누름(key press) 또는 입력 액션(input action) 전송
`game_mouse_move`	마우스 이동

런타임 검사 (Runtime Inspection) (3개 도구)

도구 (Tool)	설명 (Description)
`game_get_ui`	모든 가시적인 UI 요소 가져오기
`game_get_scene_tree`	전체 씬 트리 구조 가져오기
`game_get_node_info`	상세한 노드 자기 성찰 (introspection)

런타임 코드 실행 (Runtime Code Execution) (1개 도구)

도구 (Tool)	설명 (Description)
`game_eval`	반환 값(return values)과 함께 임의의 GDScript 실행

런타임 노드 조작 (Runtime Node Manipulation) (7개 도구)

도구 (Tool)	설명 (Description)
`game_get_property`	모든 노드 속성 (property) 가져오기
`game_set_property`	모든 노드 속성 (property) 설정하기 (자동 타입 변환 포함)
`game_call_method`	노드의 모든 메서드 (method) 호출하기
`game_instantiate_scene`	실행 중인 트리 (tree)에 PackedScene 추가하기
`game_remove_node`	트리 (tree)에서 노드 제거하기
`game_change_scene`	다른 씬 (scene)으로 전환하기
`game_reparent_node`	노드를 새로운 부모 (parent)로 이동하기