Godot MCP Server

godot-mcp는 MCP 클라이언트가 Godot 프로젝트를 검사, 검증, 테스트, 내보내기 및 조회할 수 있게 해줍니다. 헤드리스 Godot 명령과 선택적으로 열려 있는 Godot 편집기의 실시간 상태를 지원합니다.

요구 사항

• Node.js 18 이상

• Godot 4.1 이상이 로컬에 설치되어 있어야 합니다

• project.godot이 포함된 Godot 프로젝트

실시간 편집기 도구는 아래에 설명된 MCP Bridge 애드온이 추가로 필요합니다. 나머지 도구는 헤드리스로 실행됩니다.

Related MCP server: godot-ai-mcp

설치

로컬 체크아웃에서

npm install
npm run build

npm에서 (게시 후)

npx -y @zbrkic/godot-mcp --project /path/to/godot-project --godot /path/to/godot

MCP 클라이언트 구성

항상 프로젝트 경로를 제공하세요. MCP 데스크톱 클라이언트는 일반적으로 자체 작업 디렉터리에서 서버를 시작하므로 자동 프로젝트 검색만으로는 신뢰할 수 없습니다.

{
  "mcpServers": {
    "godot": {
      "command": "npx",
      "args": ["-y", "@zbrkic/godot-mcp"],
      "env": {
        "GODOT_PROJECT_PATH": "C:/Source/my-game",
        "GODOT_PATH": "C:/Program Files/Godot/Godot_v4.5.1-stable_win64_console.exe"
      }
    }
  }
}

동등한 명령줄 옵션은 다음과 같습니다:

godot-mcp --project /path/to/godot-project --godot /path/to/godot

GODOT_PATH/--godot는 godot 실행 파일이 이미 PATH에 있는 경우에만 선택 사항입니다. Windows에서는 _console.exe 실행 파일이 선호됩니다.

실시간 편집기 도구 활성화

1. godot-plugin/addons/mcp_bridge를 <your-project>/addons/mcp_bridge로 복사합니다.

2. Godot에서 Project > Project Settings > Plugins를 열고 MCP Bridge를 활성화합니다.

3. 실시간 도구를 사용하는 동안 Godot 편집기를 열어 두세요.

브리지는 기본적으로 127.0.0.1:7000에서 수신 대기합니다. project.godot에서 mcp/plugin/port를 설정하여 재정의할 수 있습니다. 서버는 위에서 구성한 프로젝트에서 해당 설정을 읽습니다. 프로덕션 내보내기 사전 설정에서 addons/mcp_bridge/*를 제외하세요.

도구

• 프로젝트 및 내보내기: get_project_settings, list_export_presets, export_project

• 테스트 및 검증: run_tests, validate_scene, validate_script, run_scene, format_gdscript

• 씬 및 리소스: inspect_scene_tree, find_nodes, get_node_properties, get_node_connections, list_resources, get_resource_dependencies, resolve_path, get_resource_info

• 문서: verify_api, get_help

• 실시간 편집기: get_editor_selection, get_open_scenes

대부분의 도구는 success, data, errors, warnings 및 타이밍 메타데이터가 포함된 구조화된 JSON 결과를 반환합니다.

개발 및 검증

npm test              # TypeScript build plus MCP handshake and parser tests
npm run test:godot    # GDScript syntax checks; requires GODOT_PATH or godot on PATH
npm pack --dry-run    # Inspect the files that would be published

GitHub Actions는 푸시 및 풀 리퀘스트에서 Node/MCP 테스트와 Godot 애드온 검사를 모두 실행합니다.

릴리스 체크리스트

1. package.json에서 버전을 업데이트합니다.

2. npm test, npm run test:godot, npm pack --dry-run을 실행합니다.

3. npm publish로 게시하고 일치하는 GitHub 릴리스를 만듭니다.

라이선스

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여됩니다.