youichi-uda/godot-mcp-pro

Godot MCP Pro – AI 기반 Godot 에디터 브리지

무엇인가요 – 대규모 언어 모델 어시스턴트(Claude, Copilot, Cursor 등)가 실시간으로 Godot 에디터를 제어할 수 있는 유료 애드온입니다. 이는 Node.js로 작성된 Model Context Protocol(MCP) 서버를 통해 WebSocket(기본 포트 6505)을 통해 에디터 플러그인과 통신함으로써 구현됩니다. 서버는 프로젝트 관리, 장면 그래프 조작, 스크립팅, 에디터 UI, 입력 시뮬레이션, 런타임 인스펙션, 애니메이션, 물리, 내보내기, 테스트 등 187개의 JSON-RPC 도구를 공개합니다.

왜 중요한가요 – 에디터 API를 RPC 호출로 노출함으로써 LLM은 프로젝트 구조를 보며, 노드를 편집하고, 스크립트를 실행하며, 스크린샷을 캡처하고, 입력을 시뮬레이션하며, 심지어 Android로 배포할 수 있습니다. 모델이 파일을 직접 읽거나 쓸 필요 없이, 완전히 상호작용적이고 코드 없이 게임 개발이 가능해지며, AI는 인간처럼 에디터 내에서 반복, 테스트, 디버깅을 수행할 수 있습니다.

작동 방식

1. Godot 플러그인 설치 – addons/godot_mcp/를 프로젝트에 복사하고 에디터 설정에서 활성화합니다.
2. MCP 서버 실행 – 서버는 유료 패키지에서만 제공됩니다. 추출 후 npm install && npm run build를 실행하면 build/index.js 실행 파일이 생성됩니다.
3. AI 클라이언트 구성 – .mcp.json 파일에 mcpServers.godot‑mcp‑pro 항목을 추가하고 빌드된 Node 스크립트를 지정합니다(옵션으로 --lite, --minimal, --3d 플래그를 사용해 모델의 컨텍스트 창 제한에 맞게 도구 세트를 제한할 수 있음).
4. 연결 – AI 어시스턴트는 stdio/MCP를 통해 서버와 통신하며, 서버는 WebSocket을 통해 JSON-RPC 호출을 Godot 플러그인으로 전달하고 요청된 에디터 작업을 실행합니다.
5. 사용 – AI 측에서 187개 도구 중 하나를 호출할 수 있습니다. 예: project info, node add --type CharacterBody3D --name Player, simulate_key "Space", run_test_scenario, deploy_to_android.

모드 및 도구 수 제한

모드	공개된 도구	일반적인 클라이언트
풀(기본값)	187	Claude Code, VS Code Copilot, Cursor(하드 제한 없음)
3D (--3d)	100	3D 도구가 필요하지만 100개로 제한되는 클라이언트
라이트 (--lite)	88	Windsurf, JetBrains Junie, Gemini CLI
미니멀 (--minimal)	35	OpenCode, 매우 작은 컨텍스트 창을 가진 로컬 LLM

주요 기능

• Undo/Redo 통합 – 모든 변경 사항은 Ctrl+Z로 되돌릴 수 있습니다.
• 스마트 타입 파싱 – "Vector2(100,200)" 또는 "#ff0000"과 같은 문자열이 자동으로 Godot 타입으로 변환됩니다.
• 자동 재연결 및 허트비트 – 강력한 연결 처리 기능.
• 도움이 되는 오류 메시지 – RPC 오류 응답에 다음 단계 제안이 포함됩니다.
• CLI 포알백 – 명령줄 클라이언트(cli.js)를 사용하면 MCP 없이도 동일한 도구를 제어할 수 있으며, 터미널 전용 환경에 유용합니다.

설치 체크리스트

1. server/ 폴더를 확보하기 위해 전체 패키지(구매해 주세요, Buy Me a Coffee 또는 itch.io)를 구매합니다.
2. addons/godot_mcp/ 디렉터리를 Godot 프로젝트에 복사하고 플러그인을 활성화합니다.
3. Node 서버를 빌드합니다(npm install && npm run build).
4. .mcp.json에 적절한 항목을 추가합니다(필요에 따라 모드 플래그를 선택합니다).
5. Godot을 시작하고 에디터를 열어두며 AI 어시스턴트를 실행합니다.

라이선스 및 배포 – 이 공개 리포지토리의 플러그인 코드는 무료로 오픈소스입니다. MCP 서버 바이너리와 전체 기능은 유료 패키지에서만 배포되며, 리포지토리는 명시적으로 server/ 디렉터리가 공개 리포지토리에서 제외되어 있음을 기재하고 있습니다.

---

Godot MCP Pro는 진정한 AI 중심 도구로, 대규모 언어 모델과 Godot 게임 엔진을 연결하여 개발자(또는 AI 어시스턴트)가 Godot 프로젝트의 거의 모든 측면에 대해 프로그래밍 가능하고 실시간으로 제어할 수 있도록 합니다.