Godot MCP 서버

Godot 4.x 게임 개발을 위한 포괄적인 FastMCP 서버입니다. AI 지원 워크플로를 위한 도구를 제공합니다: 프로젝트 관리, 파일 작업, 에셋 검색, GDScript 개발, 선택적 Godot 실행.

기여하기 · 보안

보안 모델: 모든 Godot 프로젝트, 파일 쓰기, Asset Library 다운로드는 사용자 머신의 단일 작업 공간 디렉터리(기본값 ~/godot-games)로 제한됩니다. 서버는 해당 트리 밖의 경로를 거부합니다. 작업 공간 설정을 참조하세요.

코드 실행: godot_run_game 및 godot_execute_script는 서버 환경에 GODOT_MCP_ALLOW_GODOT_EXEC가 필요합니다. 배포된 MCP JSON 구성은 이 값을 **1**로 설정하므로 복사-붙여넣기 후에 이 도구들이 작동합니다. 해당 env 없이 python godot_mcp_server.py를 실행하면 내보낼 때까지 실행이 여전히 꺼져 있습니다. IDE 설치를 잠그려면 변수를 제거하거나 0으로 설정하세요. Godot 실행(환경)을 참조하세요.

HTTP 전송: 0.0.0.0 또는 ::에 바인딩하면 MCP 서버가 모든 네트워크 인터페이스에 노출됩니다. 방화벽이나 VPN을 사용하지 않는 한 127.0.0.1을 선호하세요.

심볼릭 링크: GODOT_MCP_ROOT는 심볼릭 링크를 따라간 상태로 확인됩니다. 사용자가 제어하는 실제 디렉터리를 지정하세요.

기능

프로젝트 관리

• Godot 프로젝트 자동 감지(project.godot); 작업 공간 아래의 모든 프로젝트 나열(godot_list_projects)

• 작업 공간 아래에 새 프로젝트 생성(godot_create_project)

• 프로젝트 설정 및 구성 파싱; 오토로드 및 에디터 플러그인 상태 나열(플러그인은 읽기 전용)

• 변경 후 프로젝트 캐시 새로 고침

파일 작업

• 씬(.tscn), 스크립트(.gd), 리소스(.tres) 읽기/쓰기

• 템플릿에서 새 스크립트, 씬, 리소스 생성

• 콘텐츠 교체로 기존 파일 편집

• 씬 및 스크립트 구문 검증

코드 생성

• CharacterBody2D/3D 이동 컨트롤러

• 상태 머신 패턴

• 사용자 정의 리소스

• 시그널/export가 포함된 노드 스크립트

에셋 관리

• 확장자, 패턴, glob으로 에셋 검색

• 사용하지 않는 에셋 찾기

• 정규식으로 파일 내용 검색

• Godot Asset Library 검색 및 다운로드

• GitHub에서 Godot 저장소 찾아보기

런타임 통합

• Godot 실행 파일 찾기

• Godot 버전 확인

• 게임 헤드리스 실행

• GDScript 코드 실행

• Godot 로그 읽기

• 파일 감시자 구성

Related MCP server: Godot MCP

설치

# From PyPI-style editable install (recommended for contributors)
pip install -e .

# Or minimal deps only
pip install -r requirements.txt

콘솔 진입점(pip install -e . 이후): godot-mcp-server(python godot_mcp_server.py와 동일).

작업 공간 설정(필수)

MCP 서버는 하나의 루트 폴더 아래에 있는 Godot 프로젝트에서만 작동합니다. 이는 어시스턴트가 시스템의 임의 경로를 읽거나 쓰지 못하게 합니다.

1. 기본 폴더 생성(머신당 한 번):

   mkdir -p ~/godot-games

2. 모든 Godot 게임을 그곳에 넣기 — 각 게임은 project.godot을 포함하는 자체 하위 디렉터리입니다. 예:

   ~/godot-games/
     my-platformer/     ← open this folder in your editor
       project.godot
       ...
     another-game/
       project.godot

3. IDE 작업 공간을 ~/godot-games/.../your-game(또는 ~/godot-games 아래의 상위 폴더)에서 열어 MCP 프로세스가 현재 작업 디렉터리에서 project.godot을 발견할 수 있게 하세요.

4. 사용자 지정 위치: 서버를 시작하기 전에 절대 경로를 설정하세요:

   export GODOT_MCP_ROOT="/path/to/your/godot-games"
   python godot_mcp_server.py

   Cursor / Claude / 기타 MCP 구성에서 env를 추가하세요:

   "env": {
     "GODOT_MCP_ROOT": "/path/to/your/godot-games"
   }

   설정하지 않으면 기본값은 **$HOME/godot-games**입니다. 서버는 시작 시 해당 디렉터리가 없으면 생성합니다.

5. 런타임에 확인: 도구 godot_get_workspace를 호출하거나 리소스 project://workspace를 읽어 활성 작업 공간 경로를 확인하세요.

도구가 프로젝트를 찾지 못했다고 보고하면 cwd가 작업 공간 밖에 있거나 project_path가 GODOT_MCP_ROOT 밖을 가리키는 것입니다.

Godot 실행(환경)

게임을 실행하거나 GDScript를 실행하는 것은 사용자 권한으로 코드를 실행하는 것입니다(터미널에서 Godot을 시작하는 것과 동일). 서버는 **GODOT_MCP_ALLOW_GODOT_EXEC**이 허용된 "켜짐" 값으로 설정된 경우에만 godot_run_game / godot_execute_script를 활성화합니다.

배포 구성(기본 허용): 이 저장소의 모든 예제 JSON(mcp_config.json, mcp_config.cursor.json 등)에는 다음이 포함됩니다:

"env": {
  "GODOT_MCP_ALLOW_GODOT_EXEC": "1"
}

따라서 그중 하나를 IDE에 복사하면 별도의 단계 없이 실행이 허용됩니다. 다른 키(예: GODOT_MCP_ROOT)를 같은 env 객체에 병합하세요.

MCP 구성 없는 CLI: python godot_mcp_server.py를 실행해도 이 변수는 설정되지 않습니다. export GODOT_MCP_ALLOW_GODOT_EXEC=1(또는 래퍼 스크립트 사용) 전까지 실행 도구는 차단된 상태로 유지됩니다.

더 엄격한 설정: env에서 GODOT_MCP_ALLOW_GODOT_EXEC을 삭제하거나 0 / false / no / off로 설정한 다음 MCP 클라이언트를 다시 시작하세요.

허용되는 "켜짐" 값: 1, true, yes, on(대소문자 구분 없음). godot_get_workspace를 호출하고 godot_exec_allowed를 확인하여 확인하세요.

사용법

CLI(stdio - Claude Code/Cursor용)

python godot_mcp_server.py

HTTP 서버

python godot_mcp_server.py --transport http --port 8765

구성

기본 ~/godot-games를 사용하지 않는 경우 MCP 서버 env에 GODOT_MCP_ROOT를 설정하세요. 작업 공간 설정을 참조하세요. 아래 배포 스니펫에는 GODOT_MCP_ALLOW_GODOT_EXEC이 포함되어 있습니다. Godot 실행(환경)을 참조하세요.

서버 경로: 예제에서는 MCP 프로세스가 스크립트가 있는 폴더(예: 이 저장소를 클론한 폴더)를 작업 디렉터리로 사용하여 실행된다고 가정하고 "args": ["godot_mcp_server.py"]를 사용합니다. 서버가 시작되지 않으면 해당 값을 사용자 머신의 godot_mcp_server.py에 대한 절대 경로로 바꾸세요.

에디터에 설치

섹션을 펼치고 JSON을 도구가 기대하는 파일에 붙여넣으세요. 동일한 godot 서버 블록이 복사-붙여넣기용으로 mcp_config.*.json으로 저장소에 있습니다.

macOS / Linux(프로젝트 또는 사용자 구성) — Settings → MCP → 새 전역 MCP 서버 추가 또는 프로젝트 루트에 .cursor/mcp.json 생성:

{
  "mcpServers": {
    "godot": {
      "command": "python3",
      "args": ["godot_mcp_server.py"],
      "env": {
        "GODOT_MCP_ALLOW_GODOT_EXEC": "1"
      }
    }
  }
}

Windows — MCP 호스트의 PATH에 python이 없으면 런처 또는 python.exe의 전체 경로를 사용하고, args에는 절대 경로를 선호하세요:

{
  "mcpServers": {
    "godot": {
      "command": "cmd",
      "args": ["/c", "python", "C:\\path\\to\\godot-mcp-server\\godot_mcp_server.py"],
      "env": {
        "GODOT_MCP_ALLOW_GODOT_EXEC": "1"
      }
    }
  }
}

~/godot-games를 사용하지 않으면 env에 GODOT_MCP_ROOT를 병합하세요(작업 공간 설정 참조).

VS Code 빌드에서 제공하는 MCP / 에이전트 설정을 사용하세요(버전과 확장에 따라 보통 Settings → MCP 또는 프로젝트 .vscode/mcp.json). Cursor와 같은 구조를 붙여넣으세요:

{
  "mcpServers": {
    "godot": {
      "command": "python3",
      "args": ["godot_mcp_server.py"],
      "env": {
        "GODOT_MCP_ALLOW_GODOT_EXEC": "1"
      }
    }
  }
}

작업 공간 폴더가 저장소 루트가 아니면 args에 절대 경로를 사용하세요.

앱 구성 파일을 편집하세요:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "godot": {
      "command": "python3",
      "args": ["/absolute/path/to/godot_mcp_server.py"],
      "env": {
        "GODOT_MCP_ALLOW_GODOT_EXEC": "1"
      }
    }
  }
}

저장 후 Claude Desktop을 다시 시작하세요.

~/.claude/settings.json에 병합하세요(또는 CLI가 지원하는 경우 claude mcp add 사용 — claude mcp --help 확인):

{
  "mcpServers": {
    "godot": {
      "command": "python3",
      "args": ["godot_mcp_server.py"],
      "env": {
        "GODOT_MCP_ALLOW_GODOT_EXEC": "1"
      },
      "description": "Godot 4.x game development server"
    }
  }
}

macOS / Linux: ~/.codeium/windsurf/mcp_config.json을 편집하거나 **CMD+SHIFT+P → “Windsurf: Configure MCP Servers”**를 사용하세요.

{
  "mcpServers": {
    "godot": {
      "command": "python3",
      "args": ["godot_mcp_server.py"],
      "env": {
        "GODOT_MCP_ALLOW_GODOT_EXEC": "1"
      },
      "description": "Godot 4.x game development - project, scenes, scripts, assets, runtime"
    }
  }
}

위와 동일한 JSON 형태로 Roo의 MCP 설정(프로젝트 또는 전역)에 붙여넣으세요. 저장소 사본: roo_code_mcp.json.

{
  "mcpServers": {
    "godot": {
      "command": "python3",
      "args": ["godot_mcp_server.py"],
      "env": {
        "GODOT_MCP_ALLOW_GODOT_EXEC": "1"
      },
      "description": "Godot 4.x game dev - project, scenes, scripts, assets, runtime"
    }
  }
}

최소 stdio 구성 — 이 저장소의 mcp_config.json과 동일:

{
  "mcpServers": {
    "godot": {
      "command": "python3",
      "args": ["godot_mcp_server.py"],
      "env": {
        "GODOT_MCP_ALLOW_GODOT_EXEC": "1"
      },
      "description": "Godot 4.x game development server - file ops, asset management, runtime integration"
    }
  }
}

제한(DoS / 악용 방지)

• 정규식 검색(godot_search_content): 패턴 길이 제한, 일치 목록 제한, 2MiB보다 큰 파일은 건너뜁니다. 악의적인 정규식은 여전히 비용이 클 수 있으므로 패턴을 단순하게 유지하세요.

• 에셋 zip 다운로드: 최대 다운로드 크기, 파일별 압축 해제 크기, 총 압축 해제 크기, 파일 수가 압축 해제 전에 적용됩니다(godot_mcp_server.py 상단 근처의 상수 참조).

• Asset Library ID: godot_get_asset_info / godot_download_asset의 asset_id는 숫자만 허용됩니다.

HTTP 모드(원격)

잘 알지 못하면 루프백을 사용하세요:

python godot_mcp_server.py --transport http --host 127.0.0.1 --port 8765

모든 인터페이스에 바인딩(--host 0.0.0.0)하면 경고가 기록되고 이 서버에서 인증 없이 MCP가 LAN에 노출됩니다.

그런 다음 command 대신 serverUrl을 사용하세요:

{
  "mcpServers": {
    "godot": {
      "serverUrl": "http://localhost:8765/mcp"
    }
  }
}

동일한 프로젝트에 하나의 전송만 실행하세요(stdio 또는 HTTP). 동시에 둘 다 실행하면 MCP 세션이 충돌할 수 있습니다.

도구 참조

40개의 MCP 도구가 godot_mcp_server.py에 등록되어 있습니다(@mcp.tool 검색). 요약:

에디터 플러그인: 이 서버는 project.godot에 [editor_plugins] 섹션을 쓰지 않습니다 (열려 있는 에디터와의 충돌 방지). 위 도구를 통해 애드온을 설치하세요. 사용자는 Godot의 프로젝트 설정 → 플러그인에서 플러그인을 활성화합니다. godot_list_editor_plugins를 사용하여 확인하세요.

리소스

예제

플랫포머 플레이어 만들기

# Using template
create_code_template("character_body_2d", "Player")

에셋 찾기

# All PNG files
find_assets([".png", ".jpg"])

# Unused assets
find_unused_files()

Asset Library 검색

search_assetlib("platformer")
# => [{title: "PlatformerController2D", ...}]

get_asset_info("1062")
# => {title, author, description, license, download_url}

게임 헤드리스 실행

GODOT_MCP_ALLOW_GODOT_EXEC 필요 (배포되는 MCP JSON 구성에 포함됨).

run_game(headless=True, quit_after_seconds=30)

요구 사항

• Python 3.10+

• 의존성: fastmcp, urllib3 (pyproject.toml 참조)

개발

pip install -e ".[dev]"
ruff check godot_mcp_server.py tests
pytest

지속적 통합은 Python 3.10–3.14에서 실행됩니다 (.github/workflows/ci.yml 참조). Dependabot이 pip와 GitHub Actions에 대해 매주 PR을 엽니다.

선택 사항: pip install pre-commit && pre-commit install은 .pre-commit-config.yaml을 사용합니다.

GitHub에 게시

1. GitHub에 빈 리포지토리를 생성합니다 (로컬에 이미 있으면 README/license를 포함하지 않음), 예: godot-mcp-server.

2. 원격 저장소를 추가하고 푸시합니다:

cd /path/to/godot-mcp-server
git remote add origin https://github.com/YOUR_USER/godot-mcp-server.git
git push -u origin main

또는 GitHub CLI 사용: gh repo create godot-mcp-server --public --source=. --remote=origin --push

첫 번째 푸시 후 CI는 모든 푸시와 PR에서 실행됩니다. 다른 계정이나 조직을 사용하는 경우 README 배지 URL의 sterion66을 교체하세요.

라이선스

MIT