godot-mcp

Godot MCP는 AI 에이전트와 Godot 게임 엔진을 연결하는 Model Context Protocol(MCP) 서버입니다. 이 서버는 AI 어시스턴트가 편집기 실행, 디버그 모드로 프로젝트 실행, 콘솔 출력 캡처, 실행 흐름 제어를 통해 Godot 프로젝트와 직접 상호작용할 수 있게 합니다. 또한 씬 생성, 사용자 정의 속성을 가진 노드 추가, 스프라이트 로드, 3D 씬을 MeshLibrary 리소스로 내보내기, Godot 4.4+용 UID 참조 관리 등 씬 관리 기능을 제공합니다. ## 주요 기능 - **편집기 및 프로젝트 제어**: Godot 편집기 실행, 디버그 모드로 프로젝트 실행, 프로그래밍 방식으로 중지 - **디버그 출력 캡처**: 실시간 피드백을 위한 콘솔 출력 및 오류 메시지 검색 - **프로젝트 분석**: 디렉토리의 프로젝트 나열, 상세 프로젝트 구조 정보 확인, 설치된 Godot 버전 검색 - **씬 관리**: - 지정된 루트 노드 유형으로 새 씬 생성 - 사용자 정의 속성으로 기존 씬에 노드 추가 - Sprite2D 노드에 스프라이트/텍스처 로드 - GridMap용 MeshLibrary 리소스로 3D 씬 내보내기 - 변형 옵션으로 씬 저장 - **UID 관리** (Godot 4.4+): 파일의 UID 가져오기 및 리소스 재저장으로 UID 참조 업데이트 ## 아키텍처 서버는 하이브리드 방식을 사용합니다: 1. **직접 명령**: 간단한 작업(편집기 실행, 버전 확인)은 Godot의 내장 CLI 명령을 사용 2. **번들 작업 스크립트**: 복잡한 작업(씬 생성, 노드 조작)은 작업 유형과 매개변수를 JSON으로 받는 단일 포괄 GDScript 파일(`godot_operations.gd`)을 사용하여 임시 파일 생성 없이 유연하게 실행 ## 요구 사항 - Godot 엔진 설치 - Node.js (>=18.0.0) 및 npm - MCP 호환 AI 에이전트 (예: Claude Code, Cursor) ## 빠른 시작 Claude Code의 경우: ```bash claude mcp add godot -- npx @coding-solo/godot-mcp ``` Cursor의 경우 설정에서 명령어 `npx @coding-solo/godot-mcp`로 MCP 서버를 추가합니다. ## 구성 환경 변수: - `GODOT_PATH`: Godot 실행 파일 경로 (자동 감지 재정의) - `DEBUG`: 상세 서버 측 로깅을 위해 `"true"`로 설정 ## 문제 해결 - **Godot를 찾을 수 없음**: `GODOT_PATH` 환경 변수 설정 - **연결 문제**: 서버가 실행 중인지 확인하고 AI 어시스턴트 재시작 - **잘못된 프로젝트 경로**: 경로에 `project.godot` 파일이 포함되어 있는지 확인 - **빌드 문제**: `npm install` 실행하여 의존성 설치 ## 라이선스 MIT 라이선스