고도 MCP

지엑스피1

Godot 게임 엔진과 상호작용하기 위한 MCP(모델 컨텍스트 프로토콜) 서버입니다.

소개

Godot MCP를 사용하면 AI 어시스턴트가 Godot 편집기를 실행하고, 프로젝트를 실행하고, 디버그 출력을 캡처하고, 프로젝트 실행을 제어할 수 있습니다. 이 모든 작업이 표준화된 인터페이스를 통해 가능합니다.

이러한 직접적인 피드백 루프는 클로드와 같은 AI 보조원이 실제 Godot 프로젝트에서 무엇이 효과적이고 무엇이 효과적이지 않은지 이해하는 데 도움이 되며, 이를 통해 더 나은 코드 생성 및 디버깅 지원이 가능해집니다.

특징

Godot 편집기 실행 : 특정 프로젝트의 Godot 편집기를 엽니다.
Godot 프로젝트 실행 : 디버그 모드에서 Godot 프로젝트 실행
디버그 출력 캡처 : 콘솔 출력 및 오류 메시지 검색
제어 실행 : Godot 프로젝트를 프로그래밍 방식으로 시작 및 중지
Godot 버전 가져오기 : 설치된 Godot 버전을 검색합니다.
Godot 프로젝트 목록 : 지정된 디렉토리에서 Godot 프로젝트 찾기
프로젝트 분석 : 프로젝트 구조에 대한 자세한 정보를 얻으세요
장면 관리 :
- 지정된 루트 노드 유형으로 새 장면을 만듭니다.
- 사용자 정의 가능한 속성을 사용하여 기존 장면에 노드 추가
- 스프라이트와 텍스처를 Sprite2D 노드에 로드합니다.
- GridMap에 대한 MeshLibrary 리소스로 3D 장면 내보내기
- 변형 생성을 위한 옵션으로 장면 저장
UID 관리 (Godot 4.4+):
- 특정 파일의 UID 가져오기
- 리소스를 다시 저장하여 UID 참조를 업데이트합니다.

요구 사항

시스템에 Godot Engine이 설치되었습니다.
Node.js와 npm
MCP(Cline, Cursor 등)를 지원하는 AI 어시스턴트

설치 및 구성

1단계: 설치 및 빌드

먼저, 저장소를 복제하고 MCP 서버를 빌드합니다.

git clone https://github.com/Coding-Solo/godot-mcp.git
cd godot-mcp
npm install
npm run build

2단계: AI Assistant로 구성

옵션 A: Cline으로 구성

Cline MCP 설정 파일( ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json )에 다음을 추가합니다.

{
  "mcpServers": {
    "godot": {
      "command": "node",
      "args": ["/absolute/path/to/godot-mcp/build/index.js"],
      "env": {
        "DEBUG": "true"                  // Optional: Enable detailed logging
      },
      "disabled": false,
      "autoApprove": [
        "launch_editor",
        "run_project",
        "get_debug_output",
        "stop_project",
        "get_godot_version",
        "list_projects",
        "get_project_info",
        "create_scene",
        "add_node",
        "load_sprite",
        "export_mesh_library",
        "save_scene",
        "get_uid",
        "update_project_uids"
      ]
    }
  }
}

옵션 B: 커서로 구성

커서 UI 사용:

커서 설정 > 기능 > MCP 로 이동하세요.
+ 새 MCP 서버 추가 버튼을 클릭하세요
양식을 작성하세요:
- 이름: godot (또는 원하는 이름)
- 유형: command
- 명령어: node /absolute/path/to/godot-mcp/build/index.js
"추가"를 클릭하세요
도구 목록을 채우려면 MCP 서버 카드의 오른쪽 상단에 있는 새로 고침 버튼을 눌러야 할 수도 있습니다.

프로젝트별 구성 사용:

프로젝트 디렉토리에 .cursor/mcp.json 이라는 파일을 만들고 다음 내용을 넣으세요.

{
  "mcpServers": {
    "godot": {
      "command": "node",
      "args": ["/absolute/path/to/godot-mcp/build/index.js"],
      "env": {
        "DEBUG": "true"                  // Enable detailed logging
      }
    }
  }
}

3단계: 선택적 환경 변수

다음 환경 변수를 사용하여 서버 동작을 사용자 정의할 수 있습니다.

GODOT_PATH : Godot 실행 파일의 경로(자동 감지 무시)
DEBUG : 자세한 서버 측 디버그 로깅을 활성화하려면 "true"로 설정합니다.

예시 프롬프트

구성이 완료되면 AI 어시스턴트가 필요 시 MCP 서버를 자동으로 실행합니다. 다음과 같은 프롬프트를 사용할 수 있습니다.

"Launch the Godot editor for my project at /path/to/project"

"Run my Godot project and show me any errors"

"Get information about my Godot project structure"

"Analyze my Godot project structure and suggest improvements"

"Help me debug this error in my Godot project: [paste error]"

"Write a GDScript for a character controller with double jump and wall sliding"

"Create a new scene with a Player node in my Godot project"

"Add a Sprite2D node to my player scene and load the character texture"

"Export my 3D models as a MeshLibrary for use with GridMap"

"Create a UI scene with buttons and labels for my game's main menu"

"Get the UID for a specific script file in my Godot 4.4 project"

"Update UID references in my Godot project after upgrading to 4.4"

구현 세부 사항

건축학

Godot MCP 서버는 복잡한 작업을 위해 GDScript를 통합한 접근 방식을 사용합니다.

직접 명령 : 편집기 실행이나 프로젝트 정보 가져오기와 같은 간단한 작업은 Godot의 내장 CLI 명령을 직접 사용합니다.
번들 작업 스크립트 : 장면 생성이나 노드 추가와 같은 복잡한 작업은 모든 작업을 처리하는 단일의 포괄적인 GDScript 파일( godot_operations.gd )을 사용합니다.

이 아키텍처는 다음과 같은 여러 가지 이점을 제공합니다.

임시 파일 없음 : 임시 스크립트 파일이 필요 없으므로 시스템을 깨끗하게 유지할 수 있습니다.
간소화된 코드베이스 : 모든 Godot 작업을 하나의 (다소) 체계적으로 정리된 파일에 중앙 집중화합니다.
더 나은 유지 관리성 : 새로운 작업을 추가하거나 기존 작업을 수정하는 것이 더 쉬워집니다.
향상된 오류 처리 : 모든 작업에서 일관된 오류 보고를 제공합니다.
오버헤드 감소 : 파일 I/O 작업을 최소화하여 성능을 향상시킵니다.

번들된 스크립트는 작업 유형과 매개변수를 JSON으로 허용하므로 각 작업에 대해 임시 파일을 생성하지 않고도 유연하고 동적으로 작업을 실행할 수 있습니다.

문제 해결

Godot를 찾을 수 없습니다 . GODOT_PATH 환경 변수를 Godot 실행 파일로 설정하세요.
연결 문제 : 서버가 실행 중인지 확인하고 AI 어시스턴트를 다시 시작하세요.
잘못된 프로젝트 경로 : 경로가 project.godot 파일이 포함된 디렉토리를 가리키는지 확인하세요.
빌드 문제 : npm install 실행하여 모든 종속성이 설치되었는지 확인하세요.
커서에 대한 구체적인 내용 :
MCP 서버가 표시되고 커서 설정(설정 > MCP)에서 활성화되었는지 확인하세요.
MCP 도구는 에이전트 채팅 프로필(Cursor Pro 또는 Business 구독)을 사용해서만 실행할 수 있습니다.
"Yolo 모드"를 사용하여 MCP 도구 요청을 자동으로 실행합니다.

특허

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.

Integrations