Godot MCP Unified - AI + Godot 아키텍처

미래의 나를 위한 문서 - Godot에서 자연어로 코딩하기 위한 전체 구성

영어 버전 읽기

전체 아키텍처

                    +------------------+
                    |   Claude Code    |
                    |    (VS Code)     |
                    +--------+---------+
                             |
                             v
+----------------+  +--------+---------+  +------------------+
| Claude Desktop |->|                  |<-| ollmcp (Ollama)  |
|   (Anthropic)  |  | godot-mcp-unified|  | qwen2.5-coder:7b |
+----------------+  |   (ce serveur)   |  +------------------+
                    +--------+---------+
                             |
              +--------------+--------------+
              |                             |
              v                             v
     +--------+---------+          +--------+---------+
     |  Godot CLI       |          |  Plugin WebSocket|
     |  (--headless)    |          |  (addons/godot_  |
     |  Fallback mode   |          |   mcp/) Port 6505|
     +------------------+          +------------------+
              |                             |
              +-------------+---------------+
                            |
                            v
                   +--------+---------+
                   |  Godot Engine    |
                   |    4.5.1         |
                   +------------------+

Godot과의 통신

서버는 플러그인이 연결되어 있는지 자동으로 감지하여 최적의 모드를 사용합니다.

이 서버로 할 수 있는 작업

Godot에서 자연어로 모든 작업 수행 (83개 도구 + 20개 리소스 + 20개 프롬프트):

설치 (완료됨)

설치된 필수 구성 요소

• Node.js (MCP 서버용)

• Godot 4.5.1: C:\Dev\Godot_v4.5.1-stable_win64.exe\Godot_v4.5.1-stable_win64_console.exe

• uv (최신 Python 관리자)

• ollmcp (Ollama <-> MCP 브리지)

이 서버

cd C:\Dev\godot-mcp-unified
npm install
npm run build

구성

Claude Desktop (C:\Users\pierr\AppData\Roaming\Claude\claude_desktop_config.json)

{
  "mcpServers": {
    "godot": {
      "command": "node",
      "args": ["C:\\Dev\\godot-mcp-unified\\build\\index.js"],
      "env": {
        "GODOT_PATH": "C:\\Dev\\Godot_v4.5.1-stable_win64.exe\\Godot_v4.5.1-stable_win64_console.exe"
      }
    }
  }
}

VS Code / Claude Code (Godot 프로젝트 내 .vscode/mcp.json)

{
  "servers": {
    "godot": {
      "command": "node",
      "args": ["C:\\Dev\\godot-mcp-unified\\build\\index.js"],
      "env": {
        "GODOT_PATH": "C:\\Dev\\Godot_v4.5.1-stable_win64.exe\\Godot_v4.5.1-stable_win64_console.exe"
      }
    }
  }
}

Ollama (ollmcp를 통해)

# Lancer le bridge
ollmcp --model qwen2.5-coder:7b C:\Dev\godot-mcp-unified\build\index.js

# Ou via ollama-gateway (port 3010)

사용 가능한 Ollama 모델

참고: -chess 모델은 체스를 두기 위한 것이 아니라 FFE 시스템 프롬프트를 사용하여 chess-app 개발을 돕는 맞춤형 어시스턴트입니다.

API 참조 (83개 도구 + 20개 리소스 + 20개 프롬프트)

통계

Primitives MCP:
  Tools:     83/83   ████████████████████ 100%
  Resources: 20/20   ████████████████████ 100%
  Prompts:   20/20   ████████████████████ 100%

Qualite:
  Tests:    3170+    ████████████████████ 100% pass (69 suites)
  Coverage:  85%     █████████████████░░░  85%

Bridge Plugin:
  Avec bridge:  47 outils (utilisent WebSocket si plugin actif)
  Sans bridge:  35 outils (CLI/file I/O uniquement)

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

• launch_editor - Godot 에디터 열기

• run_project - 프로젝트 실행

• stop_project - 프로젝트 중지

• list_projects - 폴더 내 프로젝트 목록

• get_project_info - 프로젝트 정보

• get_godot_version - Godot 버전

• get_project_settings - 프로젝트 설정 읽기

• set_project_setting - 설정 수정

• manage_input_actions - 입력 액션 관리

• manage_autoloads - 오토로드 관리

• validate_project - 프로젝트 구조 검증

• convert_project - Godot 3에서 4로 프로젝트 변환

• validate_conversion - 변환 검증

• generate_docs - GDScript 문서 생성

씬 관리 (15개 도구)

• create_scene - 새 씬 생성

• add_node - 노드 추가

• edit_node - 노드 속성 수정

• remove_node - 노드 삭제

• rename_node - 노드 이름 변경

• move_node - 노드 이동 (reparent)

• duplicate_node - 노드 복제

• load_sprite - 텍스처 로드

• save_scene - 씬 저장

• instance_scene - 씬 인스턴스화

• list_scenes - 씬 목록

• get_node_tree - 씬 트리 가져오기

• connect_signal - 신호 연결

• manage_groups - 노드 그룹 관리

• export_mesh_library - MeshLibrary로 내보내기

GDScript (7개 도구)

• list_scripts - 프로젝트의 모든 .gd 스크립트 목록

• read_script - 스크립트 내용 읽기

• write_script - 스크립트 생성/수정

• delete_script - 스크립트 삭제

• attach_script - 노드에 스크립트 연결

• detach_script - 노드에서 스크립트 분리

• get_script_errors - 컴파일 오류

애니메이션 (7개 도구)

• create_animation_player - AnimationPlayer 생성

• add_animation - 애니메이션 추가

• add_animation_track - 트랙 추가 (값, 위치, 회전 등)

• set_keyframe - 전환/이징이 포함된 키프레임 설정

• create_animation_tree - AnimationTree 생성

• setup_state_machine - 상태 머신 구성

• blend_animations - 애니메이션 블렌드 구성

물리 (3개 도구)

• create_collision_shape - CollisionShape2D/3D 생성

• setup_rigidbody - RigidBody 구성 (질량, 중력)

• configure_physics_layers - 2D/3D 물리 레이어 이름 지정

타일맵 (5개 도구)

• create_tileset - 타일 크기로 TileSet 생성

• create_tilemap_layer - TileMapLayer 생성

• set_tile - 타일 배치

• paint_tiles - 배치 타일 페인팅

• import_ldtk_level - LDtk 레벨 가져오기

오디오 (3개 도구)

• create_audio_bus - 오디오 버스 생성

• setup_audio_player - AudioStreamPlayer 구성

• add_audio_effect - 효과 추가 (리버브, 딜레이, EQ)

셰이더 (2개 도구)

• create_shader - .gdshader 파일 생성

• create_shader_material - ShaderMaterial 생성

내비게이션 (2개 도구)

• create_navigation_region - NavigationRegion2D/3D 생성

• bake_navigation_mesh - 내비메시 굽기

파티클 (2개 도구)

• create_gpu_particles - GPUParticles2D/3D 생성

• create_particle_material - ParticleProcessMaterial 생성

UI (2개 도구)

• create_ui_container - 컨테이너 생성 (VBox, HBox, Grid 등)

• create_control - 컨트롤 생성 (Button, Label 등)

조명 (3개 도구)

• create_light - Light2D/3D 생성 (Directional, Omni, Spot)

• setup_environment - 환경 구성 (안개, 글로우, SSAO)

• setup_lightmapper - LightmapGI 및 베이킹 구성

에셋 (3개 도구)

• list_assets - 에셋 목록 (이미지, 오디오, 모델)

• import_asset - 외부 파일 가져오기

• reimport_assets - 강제 재가져오기

내보내기 (3개 도구)

• export_project - 프로젝트 내보내기

• export_pack - PCK만 내보내기

• list_export_presets - 내보내기 프리셋 목록

배치 작업 (1개 도구)

• batch_operations - 여러 MCP 도구를 순차적으로 실행

디버그 (5개 도구)

• get_debug_output - 콘솔 출력 가져오기

• start_debug_stream - 디버그 WebSocket 서버 시작

• stop_debug_stream - WebSocket 서버 중지

• get_debug_stream_status - 서버 상태

• take_screenshot - 스크린샷 캡처

UID (Godot 4.4+) (2개 도구)

• get_uid - 파일의 UID 가져오기

• update_project_uids - 참조 업데이트

시스템 (2개 도구)

• system_health - 시스템 상태 확인

• get_godot_version - Godot 버전

사용 예시

플레이어 캐릭터 생성

"Cree une scene Player.tscn avec un CharacterBody2D comme root,
ajoute un Sprite2D nomme 'Sprite' et un CollisionShape2D nomme 'Collision'"

프로젝트 디버깅

"Lance mon projet Godot et montre-moi les erreurs dans la console"

기존 씬 수정

"Dans la scene Player.tscn, change la position du Sprite a (100, 50)
et sa scale a 2x"

Godot 프로젝트 구조

C:\Dev\
├── jdvlh-godot-client\     <- Projet principal (pas de remote git configure!)
│   ├── project.godot
│   ├── .vscode\mcp.json    <- Config MCP pour ce projet
│   └── addons\godot_mcp\   <- Plugin MCP copie
│
├── jdvlh-godot\            <- Projet vide (a garder pour tests)
│
└── GodotDynamicDialog\     <- Fork de dynamic-dialog

코드 출처

이 서버는 3개의 오픈 소스 프로젝트 기능을 통합합니다:

참고: GDAI MCP가 존재하지만 유료($19)입니다.

머신 사양

• CPU: Ryzen 5 5600H

• RAM: 16 GB

• GPU: AMD Radeon (통합) - CUDA 없음

• 최적 양자화: Q4_K_M (품질/성능 스윗 스팟)

문제 해결

서버가 시작되지 않음

cd C:\Dev\godot-mcp-unified
npm run build

Godot을 찾을 수 없음

GODOT_PATH가 올바른 실행 파일(로그를 확인하기 위한 콘솔 버전)을 가리키는지 확인하십시오.

Claude Desktop에서 도구가 보이지 않음

설정 수정 후 Claude Desktop을 다시 시작하십시오.

유용한 명령어

# Rebuild le serveur
cd C:\Dev\godot-mcp-unified && npm run build

# Tester avec l'inspecteur MCP
npm run inspector

# Lister les modeles Ollama
ollama list

# Supprimer un modele Ollama
ollama rm nom_modele

할 일

• [ ] jdvlh-godot-client용 git remote 구성

• [ ] 중복되는 Ollama 모델 정리 (qwen2.5, gemma2, llama3.2, deepseek-coder-v2)

• [ ] 새 프로젝트로 전체 통합 테스트

최종 업데이트: 2026년 2월 11일 godot-mcp-unified v0.9.0 - 83개 도구 + 20개 리소스 + 20개 프롬프트 커버리지: 85% | 테스트: 3170+ (69개 스위트) | ISO 25010/29119/5055/27001 준수