Godot MCP Pro

Godot 4 에디터를 위한 168개의 AI 기반 도구 — AI 어시스턴트(Claude, Cursor, Cline, Copilot)를 Godot에 연결하여 자연어로 게임을 제작하세요.

작동 방식

5분 이내에 AI 어시스턴트를 Godot에 연결하세요.

1. 플러그인 설치

addons/godot_mcp/를 Godot 프로젝트에 복사하세요. 프로젝트 > 프로젝트 설정 > 플러그인에서 활성화합니다. 플러그인이 에디터 내에서 자동으로 WebSocket 서버를 시작합니다.

2. MCP 서버 빌드

cd server
npm install && npm run build

이 명령은 AI 클라이언트를 Godot 플러그인에 연결하는 TypeScript MCP 서버를 컴파일합니다.

3. AI로 빌드 시작

AI 클라이언트의 MCP 설정에 서버를 추가하세요. Godot을 열면 AI 어시스턴트가 168개의 도구에 실시간으로 액세스하여 씬 생성, 스크립트 편집, 입력 시뮬레이션 및 실행 중인 게임 분석을 수행할 수 있습니다.

MCP 클라이언트 설정

Claude Code / Claude Desktop

.claude/mcp.json에 추가하세요:

{
  "mcpServers": {
    "godot": {
      "command": "node",
      "args": ["/absolute/path/to/server/dist/index.js"]
    }
  }
}

VS Code / Cursor

.vscode/mcp.json에 추가하세요:

{
  "servers": {
    "godot": {
      "command": "node",
      "args": ["./server/dist/index.js"]
    }
  }
}

모든 stdio MCP 클라이언트

node server/dist/index.js

서버는 MCP 프로토콜을 사용하여 stdio(stdin/stdout)를 통해 통신합니다.

자동 설정 (권장)

cd server
npm run run

이 명령은 다음 작업을 자동으로 수행합니다:

MCP 서버 빌드
상위 폴더(또는 GODOT_PROJECT_PATH)에서 project.godot 감지
애드온을 addons/godot_mcp로 동기화
project.godot에서 플러그인 활성화
MCP 설정 파일 생성
AI 컨텍스트 파일 동기화

도구 카테고리

#	카테고리	도구	주요 기능
1	프로젝트	7	설정 읽기/쓰기, UID 변환
2	씬	9	생성, 열기, 재생, 정지, 인스턴스화, 저장
3	노드	14	UndoRedo를 사용한 추가/삭제/이름 변경/이동, 시그널, 그룹
4	스크립트	8	CRUD, 연결, 유효성 검사, 줄 번호 검색
5	에디터	10	스크린샷, GDScript 실행, 오류 로그, 새로고침
6	입력	7	키보드, 마우스, 액션 시뮬레이션, 시퀀스
7	런타임	19	게임 검사, 프레임 캡처, 녹화/재생, UI
8	애니메이션	6	CRUD, 트랙, 키프레임
9	애니메이션 트리	8	상태 머신, 전환, 블렌드 트리
10	타일맵	6	셀 작업 (Godot 4.3+용 TileMapLayer)
11	3D 씬	6	메시 프리미티브, .glb 가져오기, 조명 프리셋, PBR
12	물리	6	자동 2D/3D 충돌, 레이캐스트, 레이어
13	파티클	5	GPU 파티클 + 불/연기/비/눈/불꽃 프리셋
14	내비게이션	6	영역, 에이전트, 베이크, 경로 탐색
15	오디오	6	플레이어 (자동 2D/3D), 버스 효과 체인
16	테마/UI	6	StyleBoxFlat, 색상/상수/폰트 재정의
17	셰이더	6	템플릿 (canvas_item, spatial, particles, sky)
18	리소스	6	.tres CRUD, 자동 로드 관리
19	배치	8	유형별 찾기, 일괄 설정, 종속성 분석
20	테스트	6	자동화된 시나리오, 어설션, 스트레스 테스트
21	분석	4	씬 복잡도, 시그널 흐름, 사용되지 않는 리소스
22	프로파일링	2	FPS, 메모리, 물리, 렌더링 모니터
23	내보내기	3	프리셋 목록, 빌드 명령
	합계	168	+ 4개의 핵심 연결 도구

주요 기능

🧠 스마트 유형 파싱

복잡한 객체를 수동으로 구성할 필요가 없습니다. 속성 값이 자동으로 변환됩니다:

"Vector2(100, 200)"  → Vector2(100, 200)
"Color(1, 0, 0)"    → Color(1, 0, 0)
"#ff0000"            → Color(1, 0, 0)
"Color.RED"          → Color(1, 0, 0)
"true"               → true
"42"                 → 42

♻️ 모든 변경 사항에 대한 실행 취소/다시 실행

모든 add_node, delete_node, update_property, rename_node, move_node는 Godot의 UndoRedo 시스템을 거칩니다. 사용자는 Ctrl+Z로 AI의 모든 작업을 취소할 수 있습니다.

🎯 자동 2D/3D 감지

물리 바디, 충돌 모양, 오디오 플레이어, 파티클 및 내비게이션 노드는 부모가 2D인지 3D인지 자동으로 감지하여 항상 올바른 유형이 생성됩니다.

🔥 내장 프리셋

조명: 태양, 실내, 드라마틱, 스포트라이트
파티클: 불, 연기, 비, 눈, 불꽃
셰이더: canvas_item, spatial, particles, sky 템플릿
오디오 효과: 리버브, 딜레이, 컴프레서, EQ, 디스토션, 코러스, 페이저

빠른 예제

AI: godot_connect
AI: create_scene path="res://scenes/level.tscn" rootType="Node2D"
AI: add_node type="CharacterBody2D" name="Player" parentPath="."
AI: add_node type="Sprite2D" name="Sprite" parentPath="Player"
AI: update_property path="Player/Sprite" property="texture" value="res://icon.svg"
AI: setup_collision path="Player" shapeType="rectangle" size="Vector2(32, 32)"
AI: create_script path="res://scripts/player.gd" content="extends CharacterBody2D..."
AI: attach_script nodePath="Player" scriptPath="res://scripts/player.gd"
AI: save_scene
AI: play_scene
AI: simulate_key key="Space"
AI: get_game_screenshot
AI: stop_scene

아키텍처

server/src/
├── index.ts           TypeScript MCP server (stdio transport)
├── toolCatalog.ts     168 tool definitions with input schemas
└── godotBridge.ts     WebSocket client → Godot editor

addons/godot_mcp/
├── plugin.gd          Plugin entry point
├── websocket_server.gd Local WebSocket server (port 6505)
├── command_router.gd  Loads 20 handler modules, dispatches commands
└── commands/
    ├── base_commands.gd        Shared utilities (type parser, undo, I/O)
    ├── type_parser.gd          Smart string→Godot type conversion
    ├── undo_helper.gd          UndoRedo wrapper
    ├── core_commands.gd        Project, scene, node, script, editor (47 handlers)
    ├── editor_commands.gd      Screenshots, execute script (4)
    ├── input_commands.gd       Input simulation (7)
    ├── runtime_commands.gd     Game inspection & UI (15)
    ├── animation_commands.gd   Animation CRUD (6)
    ├── animation_tree_commands.gd  State machine & blend tree (8)
    ├── tilemap_commands.gd     Tile operations (6)
    ├── scene3d_commands.gd     3D scene building (6)
    ├── physics_commands.gd     Physics & collision (6)
    ├── particles_commands.gd   GPU particles + presets (5)
    ├── navigation_commands.gd  Nav regions & pathfinding (6)
    ├── audio_commands.gd       Audio players & bus effects (6)
    ├── theme_commands.gd       Theme & UI styling (6)
    ├── shader_commands.gd      Shader management (4)
    ├── resource_commands.gd    Resource & autoload (6)
    ├── batch_commands.gd       Batch operations (8)
    ├── testing_commands.gd     Testing & QA (5)
    ├── analysis_commands.gd    Code analysis (4)
    ├── profiling_commands.gd   Performance profiling (2)
    └── export_commands.gd      Export management (3)

브리지 프로토콜

WebSocket을 통한 JSON-RPC 2.0 (ws://127.0.0.1:6505):

→ { "jsonrpc": "2.0", "id": 1, "method": "add_node", "params": { "type": "Sprite2D", "name": "Player" } }
← { "jsonrpc": "2.0", "id": 1, "result": { "tool": "add_node", "data": { "path": "/root/Main/Player" } } }

브리지 URL 재정의: GODOT_WS_URL=ws://127.0.0.1:6505 node server/dist/index.js

요구 사항

Godot 4.2+ (TileMapLayer의 경우 4.3+ 권장)
Node.js 18+
모든 MCP 호환 AI 클라이언트

AI 에이전트 컨텍스트 파일

Godot 프로젝트에 배포되면, 이 컨텍스트 파일들은 AI 어시스턴트가 사용 가능한 도구를 이해하는 데 도움을 줍니다:

파일	목적	사용 대상
`addons/godot_mcp/skills.md`	워크플로우가 포함된 168개 도구 전체 참조	모든 AI 에이전트
`AGENTS.md`	아키텍처 + 기능 요약	Codex, Gemini, 에이전트
`CLAUDE.md`	빠른 참조 + 빌드 명령	Claude Code
`.github/copilot-instructions.md`	Copilot 전용 지침	GitHub Copilot

Godot MCP Bridge