Godot MCP Toolkit: an amber toolbox with a cream wrench and a blue gear, beside the wordmark "Godot · MCP · Toolkit" on a dark navy field
CI
Godot 4.2+
License: MIT
Model Context Protocol(MCP)을 통해 AI 지원 Godot 개발이 가능합니다. 이 애드온은 Godot 4.2+ 에디터를 MCP 서버로 변환합니다. 사용자가 지켜보는 동안, AI 코딩 어시스턴트가 에디터 내부에서 장면 생성, 스크립트 편집, 노드 검사, 플레이 테스트 실행 및 결과 읽기 등을 수행할 수 있습니다. 동반 npm 패키지인 @npgamedev/godot-mcp-server는 사용자의 어시스턴트가 통신하는 브릿지 역할을 합니다.
완전히 로컬에서 실행됩니다. 텔레메트리, 클라우드 서비스, 계정 정보 없음. 아무것도 기기를 벗어나지 않습니다.
본 프로젝트는 Godot Foundation이나 Anthropic과 관련이 없으며, 이들의 후원을 받지 않는 독립적인 커뮤니티 프로젝트입니다.
데스크톱 전용: Windows, macOS, Linux. 브릿지는 Node.js 22 이상이 필요합니다.
<details>
<summary>MCP가 처음이신가요?</summary>
Model Context Protocol(MCP)은 AI 어시스턴트가 외부 도구를 사용할 수 있게 하는 개방형 표준입니다. MCP 서버는 자신이 무엇을 할 수 있는지(노드 생성, 스크립트 읽기, 게임 실행 등)를 설명하며, 모든 MCP 호환 어시스턴트(Claude Code, Claude Desktop, Cursor 등)는 대화 중간에 이러한 도구를 호출할 수 있습니다. 이 애드온은 Godot 에디터를 그러한 도구 제공자 중 하나로 변환하고, 동반 npm 서버가 사용자의 어시스턴트가 통신하는 브릿지 역할을 합니다.
</details>
📐 **아키텍처 →**는 이 툴킷이 어떻게 구축되었는지(하위 시스템, 에디터/런타임 분리, 전송 및 계약 표면)를 다룹니다. 또한 npgamedev.github.io/godot-mcp-toolkit/architecture에서도 렌더링됩니다.
왜 이것을 사용해야 할까요?
작업 흐름에 맞춰 설계되었을 뿐, 그 반대는 아닙니다.
가장 많은 것을 보여주는 숫자는 **150개 이상의 작업(operations)**입니다. 이것이 도구 키트가 실제로 수행하는 핵심 작업입니다: 노드를 생성하고, 타일맵 셀을 칠하며, 애니메이션 트랙에 키를 지정하고, 플레이 테스트 중간에 라이브 노드를 읽는 등의 작업을 포함하여 약 150가지 이상의 작업이 가능합니다. 이러한 작업들은 **최대 112개의 도구(tool)**로 패키징됩니다 (항상 활성화된 코어와 28개의 온디맨드 그룹). 그 이유는 하나의 도구가 클라이언트의 도구 예산 내 슬롯을 차지하고, 하나의 작업은 실제로 수행할 수 있는 항목이기 때문입니다. 관련 동작들은 하나의 도구 뒤에 배치되어 목록을 간결하게 유지하면서도, 작업 개수가 폭넓은 범위를 솔직하게 보여줍니다. 일부 작업은 버전 제한이 있어 구형 Godot 버전(4.2까지)에서는 더 적게 노출됩니다. '최대'는 문자 그대로의 의미입니다.
설계에는 두 가지 요소가 동력을 제공하며, 이들은 동일한 중요도를 가집니다:
- 고정된 상한선 없이 확장할 수 있습니다. 확장 API를 사용하면 GDScript로 자체 도구를 등록할 수 있습니다. 이 도구들은 빌트인(built-in)처럼 에이전트에 핫 리로드되어 나타나며, 추가할 수 있는 개수에 고정된 제한은 없습니다. 한계는 현재 시스템이 지원하는 범위이며, 반복될수록 그 상한선이 높아지고 확장 기능에 더 많은 여유를 제공합니다. C#/.NET 프로젝트도 같은 방식으로 확장되며, 이는 이 키트가 단순히 덧붙이는 것이 아니라 모든 프로젝트에 적합하다는 증거입니다. 휴리스틱 또는 타사 의존 도구들은 핵심 코어에서 의도적으로 제외되었으며, 확장 API가 바로 그들이 속해야 할 곳입니다.
- 결과를 확인할 수 있습니다. 에이전트의 컨텍스트 창은 예산(budget)이기 때문에, 도구 표면은 작게 시작합니다(~8,800 토큰) 그리고 에이전트가 더 많은 것을 요청할 때만 성장합니다. 아래 증거 섹션에서는 CI가 모든 빌드에서 주장하는 내용, 테스트 매니페스트가 다루는 범위, 그리고 언제 측정되었는지에 대한 내용을 명시합니다. 형용사가 아닌 링크입니다.
주로 Claude Code로 테스트되었으며, 모든 MCP 클라이언트와 호환됩니다.
빠른 시작 (Quick start)
1. 플러그인 설치 (Install the plugin)
- Godot AssetLib: 에디터 내에서 AssetLib 탭을 열고, 'Godot MCP Toolkit'을 검색한 후 다운로드(Download)하고 설치(Install)합니다.
- 수동 설치(Manual): GitHub Releases에서 다운로드하여 프로젝트의
addons/ 디렉터리에 압축을 해제합니다.
2. 활성화하기(Enable it)
프로젝트 설정(Project Settings) → 플러그인(Plugins) → Godot MCP Toolkit → **활성(Active)**에 체크합니다.
다음과 같이 표시되어야 합니다: MCP 도킹 스테이션(dock)이 하단 패널에 나타나고, 출력 로그(Output log)에 다음 내용이 출력됩니다:
[MCPServer] listening on 127.0.0.1:6550
(포트는 6550부터 6560 사이의 어느 곳일 수 있습니다. 도킹 스테이션의 상태 섹션에서 현재 사용 중인 포트를 확인할 수 있습니다). 이 줄은 에디터 내 플러그인 자체의 WebSocket 서버입니다. npm 브리지는 나중에 MCP 클라이언트가 시작하는 별도의 프로세스이며, 이 포트로 연결(dials)합니다.
3. 클라이언트 설정 작성하기(Write the client config)
플러그인이 작성하도록 합니다: **프로젝트(Project) → 도구(Tools) → MCP Toolkit → .mcp.json 쓰기(Write .mcp.json)**를 클릭합니다.
이 설정은 npx -y @npgamedev/godot-mcp-server를 통해 브리지를 실행하며, 이는 최초 연결 시 가져오므로 별도의 설치 단계가 필요 없습니다. (Node.js 22 이상 필요. 버전 확인을 위해 node --version을 실행하세요.) 만약 기기에 고정된 사본을 유지하고 싶다면, npm install -g @npgamedev/godot-mcp-server도 작동합니다.
다음과 같이 표시되어야 합니다: 프로젝트 루트에 .mcp.json 파일이 있고, 도킹 스테이션의 .mcp.json 섹션에 정상(healthy) 상태가 표시됩니다.
<details>
<summary>수동으로 .mcp.json을 작성하는 것을 선호하나요?</summary>
{
이 프로젝트를 위해 Godot MCP Toolkit을 설정하세요:
1. 클라이언트 설정을 작성합니다 (먼저 Node >= 22인지 확인하세요). 이 프로젝트에 .mcp.json 파일이 없다면, 'godot-mcp-toolkit' 서버 항목이 실행되는 파일을 생성하세요.
...
### 4. 연결하고 무언가를 요청하기
프로젝트 루트에서 MCP 클라이언트를 실행합니다. 그러면 플러그인을 감지하고 자동으로 인증합니다. 도크의 피어(peer) 개수가 증가하는 것을 볼 수 있어야 합니다.
그런 다음 아래 첫 번째 프롬프트를 시도해 보세요. 이것이 생성하는 결과물의 종류입니다:
<!-- captured: pre-1.0, Godot 4.7, 2026-07-24, human-recorded (editor + MCP dock, 1 peer connected, game running); UI-chrome shots are hand-recorded per docs/media/README.md. -->
 및 노드 생성, 열기, 닫기, 차이점 비교(diff); 노드 생성, 삭제, 부모 변경; 모든 속성 가져오기 및 설정하기; 위치 및 경계의 공간 지도(spatial map) |
| ... |
The authoritative per-tool list는 서버가 생성하는 [도구 참조](https:
## 설계 방식
몇 가지 의도적인 선택이 이 도구의 표면(tool surface)을 형성합니다:
- **통합된 도구, 계산되는 작업.** 관련된 동작들은 각기 하나의 도구를 갖는 대신 액션 매개변수(action parameter)를 가진 하나의 도구를 공유합니다. 짧은 도구 목록은 모든 클라이언트의 도구 예산에 맞고 더 적은 컨텍스트 토큰을 소모하며; 150개 이상의 작업 카운트는 이 툴킷이 실제로 얼마나 많은 작업을 수행할 수 있는지 보여줍니다.
- **읽기/쓰기 규율.** 모든 도구는 읽기 전용(read-only) 및 파괴적(destructive) 주석을 포함하고 있어, 클라이언트가 안전한 도구를 자동으로 허용하고 위험한 도구를 통제할 수 있습니다. 읽기 전용 모드는 하나의 스위치로 모든 변경 가능한 도구를 숨길 수 있습니다.
- **두 채널.** 에디터 채널은 편집 중인 장면에 대해 작동합니다. 런타임 채널은 플레이 테스트 동안 실행되는 게임에 대해 작동합니다. 이 분리는 아키텍처적입니다: 런타임 부분은 내보내기(export) 시 깨끗하게 배포되며 디버그 빌드 외부에서는 스스로 비활성화됩니다.
- **일부 것은 의도적으로 도구가 아닙니다.** 휴리스틱하거나 의견이 개입된 것들(장면 린팅, 자동 레이아웃, 밸런스 조정)은 핵심에서 제외되는데, 이는 경고를 울리는 내장 기능이 신뢰도를 떨어뜨리기 때문입니다. 확장 API가 이러한 기능들의 본거지입니다. 자신만의 기능을 추가하고, 공식 확장 패키지가 수요에 따라 뒤따를 수 있습니다.
- **버전 적응형.** 이 도구는 Godot 4.2부터 4.7까지 점진적으로 성능이 저하되지 않습니다(degrade gracefully). 버전 제한 기능들은 모호하게 실패하는 대신 자신을 명확히 보고합니다.
## 확장하기
GDScript에 자체 MCP 도구를 등록하세요: 에이전트가 호출하는 프로젝트별 헬퍼로, 내장 기능처럼 작동하며, 핫 리로드(hot-reload), 도구별 타임아웃, 취소 기능을 지원합니다. 추가할 수 있는 개수에 고정된 제한은 없습니다. 한계는 현재 시스템이 지원하는 범위이며, 매 반복마다 이 한계를 높이고 확장을 더욱 유연하게 만들기 때문에 시간이 지남에 따라 구축할 수 있는 사용자 정의 기능은 계속 증가합니다. C# 프로젝트도 지원됩니다. 배포된 [확장 가이드](addons/godot_mcp_toolkit/docs/extending.md)부터 시작하세요. 이 애드온에는 또한 AI 에이전트가 툴킷을 구동하는 능력을 향상시키는 워크플로우 스킬(workflow skill)과 확장 작성 스킬(extension-authoring skill)인 [에이전트 스킬](addons/godot_mcp_toolkit/docs/companion-skills.md)이 번들로 포함되어 있습니다. 이들을 사용하려면 스킬 폴더를 클라이언트의 스킬 디렉터리에 복사하기만 하면 됩니다.
## 작동 방식 확인 방법
CI(지속적 통합)에서 다음 수치 중 어느 하나라도 벗어나면 빌드가 실패합니다: **28개 그룹**에 걸쳐 **150개 이상의 작업**을 커버하는 **112개 도구**(항상 활성화 34개 + 메타 2개, 온디맨드 78개); 읽기 전용 모드에서 보이는 **39개 도구**.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
