/ 디렉터리 / 플레이그라운드 / Godot MCP
← 모든 서버 ↗ GitHub
● 커뮤니티 Coding-Solo ⚡ 바로 사용

Godot MCP

제작: Coding-Solo · Coding-Solo/godot-mcp

Claude에서 Godot 4 실행 — 프로젝트를 실행하고, 헤드리스로 씬을 구동하며, stdout/stderr를 캡처하여 창 전환 없이 GDScript를 반복 개선.

Godot MCP는 Godot 4 바이너리를 감싸고 편집기 + 런타임 도구를 노출합니다. Claude는 편집기를 실행하고, 프로젝트를 헤드리스로 구동하며, 단일 씬을 실행하고, stdout/stderr를 텍스트로 가져올 수 있습니다. filesystem MCP와 결합하면 루프가 이렇게 됩니다: Claude가 .gd 파일 편집 → 씬 실행 → 오류 읽기 → 수정 — 전부 채팅에서.

▶ 데모 보기 📦 설치 💡 사용 사례

왜 쓰나요

핵심 기능

라이브 데모

실제 사용 모습

godot-mcp-coding-solo.replay ▶ 준비됨
0/0

설치

클라이언트 선택

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "godot-mcp-coding-solo": {
      "command": "npx",
      "args": [
        "-y",
        "godot-mcp"
      ],
      "env": {
        "GODOT_PATH": "/Applications/Godot.app/Contents/MacOS/Godot"
      }
    }
  }
}

Claude Desktop → Settings → Developer → Edit Config 열기. 저장 후 앱 재시작.

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "godot-mcp-coding-solo": {
      "command": "npx",
      "args": [
        "-y",
        "godot-mcp"
      ],
      "env": {
        "GODOT_PATH": "/Applications/Godot.app/Contents/MacOS/Godot"
      }
    }
  }
}

Cursor는 Claude Desktop과 동일한 mcpServers 스키마 사용. 프로젝트 설정이 전역보다 우선.

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "godot-mcp-coding-solo": {
      "command": "npx",
      "args": [
        "-y",
        "godot-mcp"
      ],
      "env": {
        "GODOT_PATH": "/Applications/Godot.app/Contents/MacOS/Godot"
      }
    }
  }
}

Cline 사이드바의 MCP Servers 아이콘 클릭 후 "Edit Configuration" 선택.

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "godot-mcp-coding-solo": {
      "command": "npx",
      "args": [
        "-y",
        "godot-mcp"
      ],
      "env": {
        "GODOT_PATH": "/Applications/Godot.app/Contents/MacOS/Godot"
      }
    }
  }
}

Claude Desktop과 같은 형식. Windsurf 재시작 후 적용.

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "godot-mcp-coding-solo",
      "command": "npx",
      "args": [
        "-y",
        "godot-mcp"
      ]
    }
  ]
}

Continue는 맵이 아닌 서버 오브젝트 배열 사용.

~/.config/zed/settings.json
{
  "context_servers": {
    "godot-mcp-coding-solo": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "godot-mcp"
        ]
      }
    }
  }
}

context_servers에 추가. 저장 시 Zed가 핫 리로드.

claude mcp add godot-mcp-coding-solo -- npx -y godot-mcp

한 줄 명령. claude mcp list로 확인, claude mcp remove로 제거.

사용 사례

실전 활용법: Godot MCP

GDScript 버그에 대한 빠른 반복 루프

👤 솔로/인디 개발자 ⏱ ~20 min intermediate

언제 쓸까: 리팩토링 후 플레이어 이동이 망가졌을 때; 매분 Godot으로 전환하지 않고 Claude가 수정하게 하고 싶을 때.

사전 조건
  • Godot 4 설치됨 — godotengine.org에서 다운로드
  • GODOT_PATH 환경 변수 — Godot 바이너리를 가리키도록 설정 (macOS에서는 .app이 아님)
흐름
  1. 프로젝트 컨텍스트
    Godot: /Users/me/games/Platformer의 프로젝트 정보를 가져오세요. 오토로드 + 메인 씬을 나열하세요.✓ 복사됨
    → 프로젝트 이름, 버전, 오토로드 목록 반환됨
  2. 실패하는 씬 실행
    10초 타임아웃으로 scenes/Level1.tscn 씬을 헤드리스로 실행하세요. stderr를 보여주세요.✓ 복사됨
    → stderr가 캡처됨; 오류 라인 + 트레이스백 표시
  3. 수정 후 재실행
    오류는 'Invalid call to method move_and_slide on null'입니다. scripts/Player.gd를 읽고 원인을 찾아 수정한 다음 씬을 다시 실행하세요.✓ 복사됨
    → 파일 편집됨, 씬 재실행됨, null 오류 없음

결과: 채팅을 벗어나지 않고 5분 안에 버그를 찾아 수정

함정
  • 헤드리스 실행이 모달 대화상자에서 멈춤 — 타임아웃 사용; stderr에서 대화상자 제목 확인
  • GODOT_PATH가 잘못된 아키텍처를 가리킴 (Intel vs ARM Mac) — file $GODOT_PATH로 확인
함께 쓰기: filesystem · github

처음부터 플레이어 상태 머신 스캐폴딩

👤 새 프로젝트를 시작하는 개발자 ⏱ ~25 min intermediate

언제 쓸까: 복사-붙여넣기 없이 상태 머신 보일러플레이트(Idle/Run/Jump/Attack)가 필요할 때.

사전 조건
  • 빈 Godot 프로젝트 — 프로젝트 매니저에서 생성
흐름
  1. 파일 생성
    scripts/State.gd (기본 클래스)와 신호를 사용한 전환을 포함한 IdleState/RunState/JumpState/AttackState를 생성하세요. res://scripts/states/에 저장하세요.✓ 복사됨
    → 올바른 위치에 5개의 새 .gd 파일
  2. Player.gd 연결
    상태 머신을 인스턴스화하고 current_state에 _physics_process를 위임하도록 scripts/Player.gd를 업데이트하세요. 입력 처리는 최소로 유지하세요.✓ 복사됨
    → Player.gd에 state_machine, current_state, transitions 포함
  3. 스모크 테스트
    scenes/Player.tscn을 3초 동안 실행하세요. 런타임 오류를 확인하세요.✓ 복사됨
    → 깨끗한 실행; 게임플레이 추가 준비 완료

결과: 실제 상태를 추가할 준비가 된 작동하는 상태 머신 보일러플레이트

함정
  • State.gd에 class_name 선언을 잊음 — 추가해야 자식 클래스가 타입을 사용할 수 있음
함께 쓰기: filesystem

CI에서 gut 테스트를 헤드리스로 실행

👤 CI를 설정하는 개발자 ⏱ ~30 min advanced

언제 쓸까: 모든 푸시에 대해 GitHub Actions에서 유닛 테스트가 실행되도록 하고 싶을 때.

사전 조건
  • Gut 테스팅 애드온 — Asset Library를 통해 설치하거나 git 서브모듈로
흐름
  1. 먼저 로컬에서 실행
    Godot: addons/gut/gui/GutRunner.tscn 씬을 헤드리스로 실행하세요. 종료 코드를 캡처하세요.✓ 복사됨
    → 테스트 실행됨; 초록색이면 종료 코드 0
  2. 워크플로 생성
    이제 Ubuntu에서 godot-headless 4.x를 사용하여 동일한 작업을 수행하는 .github/workflows/test.yml을 작성하세요.✓ 복사됨
    → 적절한 Godot 설정 액션이 있는 워크플로 파일

결과: Godot 테스트를 위한 반복 가능한 CI

함정
  • 헤드리스 모드가 디스플레이 호출에서 충돌 — --headless를 사용하고 테스트에서 OS.window_*를 피할 것
함께 쓰기: github

조합

다른 MCP와 조합해 10배 효율

godot-mcp-coding-solo + filesystem

GDScript를 편집하고 빠른 루프에서 씬을 재실행

Filesystem: 점프 쿨다운을 추가하도록 scripts/Player.gd를 편집하세요. Godot: scenes/Player.tscn을 3초 동안 실행하세요. stderr를 보여주세요.✓ 복사됨
godot-mcp-coding-solo + github

Claude가 게임플레이 버그를 수정한 후 PR 열기

Godot: 씬을 재실행하여 버그가 수정되었는지 확인하세요. GitHub: 수정 사항과 관련 로그 스니펫이 포함된 PR을 열어주세요.✓ 복사됨

도구

이 MCP가 노출하는 것

도구입력언제 호출비용
get_project_info project_path: str 첫 번째 호출, 상태 확인 free
launch_editor project_path: str Godot UI 열기 free
run_project project_path, headless?: bool, timeout?: int 전체 프로젝트 스모크 테스트 free
run_scene project_path, scene_path, headless?, timeout? 단일 씬 반복 free
stop_process pid: int 막힌 실행 종료 free

비용 및 제한

운영 비용

API 쿼터
없음 — 로컬
호출당 토큰
200–8000 (stdout/stderr가 클 수 있음)
금액
무료 OSS; Godot은 무료
팁
run_scene에서 타임아웃을 적극 사용; 무한 루프가 토큰을 소비하게 두지 말 것

보안

권한, 시크릿, 파급범위

최소 스코프: execute Godot binary
자격 증명 저장: 없음
데이터 외부 송신: 로컬 전용
절대 부여 금지: arbitrary shell

문제 해결

자주 발생하는 오류와 해결

GODOT_PATH를 찾을 수 없음

Godot 바이너리의 절대 경로 설정; Mac에서는 .app 내부의 바이너리 사용

확인: $GODOT_PATH --version
헤드리스 실행이 멈춤

항상 타임아웃 전달; 모달 대화상자 또는 셰이더 컴파일을 위해 stderr 확인

잘못된 Godot 버전

MCP는 Godot 4.x 전용; 3.x 씬은 로드되지 않음

확인: godot --version

대안

Godot MCP 다른 것과 비교

대안언제 쓰나단점/장점
godot.unitynoid (mcp-godot)다른 포크를 원할 때덜 검증됨
Bevy / Rapier MCPsRust/Bevy를 사용할 때완전히 다른 엔진

더 보기

리소스

📖 GitHub에서 공식 README 읽기

🐙 열린 이슈 보기

🔍 400+ MCP 서버 및 Skills 전체 보기