Skip to main content
Glama

Gear

Made with Godot npm

Gear를 사용하면 AI 어시스턴트가 귀하의 Godot 프로젝트를 직접 실행, 검사, 수정 및 디버깅할 수 있습니다.


빠른 시작 (3분)

환경 요구 사항

  • Godot 4.x

  • Node.js 18+

  • MCP 지원 클라이언트 (Claude Desktop, Cursor, Cline 등)

1) Gear 실행

npx -y gear

또는 전역 설치:

npm install -g gear-godot-mcp
gear

2) MCP 클라이언트 설정

Claude Desktop 등 클라이언트의 설정 파일에 다음을 추가하세요:

{
  "mcpServers": {
    "godot": {
      "command": "npx",
      "args": ["-y", "gear"],
      "env": {
        "GODOT_PATH": "/path/to/godot"
      }
    }
  }
}

3) 다음 명령어들을 시도해 보세요

  • "/your/projects 디렉터리에 있는 모든 Godot 프로젝트 나열"

  • "scenes/Player.tscn 생성, 루트 노드는 CharacterBody2D로 설정"

  • "프로젝트 실행, 디버그 출력 가져오기, 오류 수정"


Related MCP server: Godot MCP Enhanced

Gear를 사용하는 이유

핵심 장점

특징

설명

실시간 피드백

게임 실행, 로그 확인, 즉각적인 수정

110개 이상의 도구

장면/스크립트/리소스/런타임/LSP/디버깅/입력/에셋 지원

토큰 효율성

기본적으로 33개의 핵심 도구만 노출하며 필요 시 활성화

동적 도구 그룹

도구 검색 시 관련 도구 그룹 자동 활성화

심층 통합

ClassDB 쿼리, 런타임 검사, 중단점 디버깅

사용 사례

  • ✅ AI를 활용해 개발 속도를 높이려는 1인 개발자

  • ✅ AI가 실제 프로젝트/런타임 상태를 이해해야 하는 팀

  • ✅ 고도화된 디버깅 워크플로우 (중단점, 스택 추적, 런타임 검사)


도구 사용 모드

도구 노출 수준

Gear는 세 가지 도구 노출 모드를 제공합니다:

모드

도구 수

설명

compact (기본값)

33 핵심 + 78 필요 시 활성화

토큰 효율적, 필요 시 로드

full

110+

전체 노출

legacy

110+

full과 동일

compact 모드의 동적 도구 그룹

compact 모드에서는 78개의 추가 도구가 22개의 동적 도구 그룹으로 구성됩니다:

도구 그룹

도구 수

설명

scene_advanced

3

노드 복제, 부모 재설정, 스프라이트 로드

runtime

4

런타임 장면 검사, 속성 수정

dap

6

중단점, 단계별 실행, 스택 추적

lsp

3

코드 완성, 호버, 심볼 목록

testing

6

스크린샷, 입력 주입

animation

5

애니메이션, 트랙, 상태 머신

resource

4

재질, 셰이더, 리소스 생성

...

...

추가 항목 존재

도구 그룹 사용 방법

1. 자동 활성화 (권장)

tool.catalog를 사용하여 관련 도구를 검색하면 일치하는 도구 그룹이 자동으로 활성화됩니다.

2. 수동 활성화

tool.groups를 사용하여 특정 도구 그룹을 수동으로 활성화합니다. "디버깅을 위해 dap 도구 그룹 활성화"

3. 비활성화

tool.groups를 사용하여 활성화된 그룹을 재설정합니다.


설치 방법

방법 A: npx (권장)

npx -y gear

방법 B: 전역 설치

npm install -g gear-godot-mcp
gear

방법 C: 소스 코드 설치

git clone https://github.com/HaD0Yun/Gear-godot-mcp.git
cd Gear-godot-mcp
npm install
npm run build
node build/index.js

기능 요약

장면 편집

  • 장면 생성, 노드 추가/삭제

  • 노드 속성 수정

  • 노드 부모 재설정

스크립트 워크플로우

  • 스크립트 생성/수정

  • 스크립트 구조 분석

  • 심볼 이름 변경

런타임 디버깅

  • 런타임 장면 트리 검사

  • 중단점 설정, 단계별 실행

  • 변수 값 확인

입력 및 스크린샷

  • 키보드/마우스 입력 주입

  • 게임 화면 캡처

  • 뷰포트 캡처

에셋 관리

  • CC0 에셋 검색 (Poly Haven, AmbientCG, Kenney)

  • 프로젝트로 에셋 다운로드


환경 변수

변수

용도

기본값

GEAR_TOOL_PROFILE

도구 노출 모드

compact

GODOT_PATH

Godot 실행 파일 경로

자동 감지

GODOT_BRIDGE_PORT

브리지 서비스 포트

6505

GEAR_TOOLS_PAGE_SIZE

도구 목록 페이지 크기

33

DEBUG

디버그 로그

false


자주 묻는 질문

문제

해결책

Godot을 찾을 수 없음

GODOT_PATH 환경 변수 설정

도구 목록이 비어 있음

MCP 클라이언트 재시작

프로젝트 경로가 유효하지 않음

project.godot 파일 존재 확인

런타임 도구가 작동하지 않음

runtime addon 플러그인 설치 및 활성화

필요한 도구를 찾을 수 없음

tool.catalog를 사용하여 관련 도구 그룹 검색 및 활성화


관련 링크

라이선스

MIT — 자세한 내용은 LICENSE를 참조하세요.

감사의 말

Available Tools

33 tools
class-infoA

[compact alias of query_class_info] Get detailed information about a specific Godot class: methods, properties, signals, enums. Use to discover available properties before calling add_node/create_resource/set_node_properties, or to find methods before call_runtime_method.

Inputs: projectPath (required), className (required), includeInherited.

class-queryA

[compact alias of query_classes] Query available Godot classes from ClassDB with filtering. Use to discover node types, resource types, or any class before using add_node/create_resource. Categories: node, node2d, node3d, control, resource, physics, physics2d, audio, visual, animation.

Inputs: projectPath (required), filter, category, instantiableOnly.

dap-outputB

[compact alias of dap_get_output] Get captured Godot DAP console output lines

Inputs: no named parameters.

editor-debug-outputA

[compact alias of get_debug_output] Retrieves console output and errors from the currently running Godot project. Use after run_project to check logs, errors, and print statements. Returns empty if no project is running.

Inputs: reason (required).

editor-launchA

[compact alias of launch_editor] Opens the Godot editor GUI for a project. Use when visual inspection or manual editing of scenes/scripts is needed. Opens a new window on the host system. Requires: project directory with project.godot file.

Inputs: projectPath (required).

editor-runA

[compact alias of run_project] Launches a Godot project in a new window and captures output. Use to test gameplay or verify script behavior. Runs until stop_project is called. Use get_debug_output to retrieve logs.

Inputs: projectPath (required), scene.

editor-statusA

[compact alias of get_editor_status] Returns the connection status of the Godot Editor Plugin bridge. Use to check if the editor is connected before using scene/resource tools that require the editor plugin.

Inputs: no named parameters.

editor-stopA

[compact alias of stop_project] Terminates the currently running Godot project process. Use to stop a project started with run_project. No effect if no project is running.

Inputs: reason (required).

editor-versionA

[compact alias of get_godot_version] Returns the installed Godot engine version string. Use to check compatibility (e.g., Godot 4.4+ features like UID). Returns version like "4.3.stable" or "4.4.dev".

Inputs: reason (required).

export-presetsA

[compact alias of list_export_presets] Lists all export presets defined in export_presets.cfg. Use before export_project to see available targets (Windows, Linux, Android, etc.).

Inputs: projectPath (required), includeTemplateStatus.

export-runA

[compact alias of export_project] Exports the project to a distributable format. Use to build final game executables. Requires export templates installed.

Inputs: projectPath (required), preset (required), outputPath (required), debug.

lsp-diagnosticsC

[compact alias of lsp_get_diagnostics] Get GDScript diagnostics from Godot Language Server for a script file.

Inputs: projectPath (required), scriptPath (required).

project-infoA

[compact alias of get_project_info] Returns metadata about a Godot project including name, version, main scene, autoloads, and directory structure. Use to understand project before modifying. Requires valid project.godot.

Inputs: projectPath (required).

project-listA

[compact alias of list_projects] Scans a directory for Godot projects (folders containing project.godot). Use to discover projects before using other tools. Returns array of {path, name}.

Inputs: directory (required), recursive.

project-setting-getA

[compact alias of get_project_setting] Reads a value from project.godot settings. Use to check game name, window size, physics settings, etc.

Inputs: projectPath (required), setting (required).

project-setting-setA

[compact alias of set_project_setting] Writes a value to project.godot settings. Use to configure game name, window size, physics, etc.

Inputs: projectPath (required), setting (required), value (required).

resource-dependenciesA

[compact alias of get_dependencies] Analyzes resource dependencies and detects circular references. Use to understand what a scene/script depends on before refactoring.

Inputs: projectPath (required), resourcePath (required), depth, includeBuiltin.

runtime-statusA

[compact alias of get_runtime_status] Checks if a Godot game instance is running and connected for live debugging. Use before other runtime tools.

Inputs: projectPath (required).

scene-createA

[compact alias of create_scene] Creates a new Godot scene file (.tscn) with a specified root node type. Use to start building new game levels, UI screens, or reusable components. The scene is saved automatically after creation.

Inputs: projectPath (required), scenePath (required), rootNodeType.

scene-node-addA

[compact alias of add_node] Adds ANY node type to an existing scene. This is the universal node creation tool — replaces all specialized create_* node tools. Supports ALL ClassDB node types (Camera3D, DirectionalLight3D, AudioStreamPlayer, HTTPRequest, RayCast3D, etc.). Set any property via the properties parameter with type conversion support (Vector2, Vector3, Color, etc.). Use query_classes to discover available node types. Use query_class_info to discover available properties for a type.

Inputs: projectPath (required), scenePath (required), nodeType (required), nodeName (required), +2 more.

scene-node-deleteA

[compact alias of delete_node] Removes a node and all its children from a scene. Use to clean up unused nodes. Cannot delete root node. Scene is saved automatically unless saveScene=false.

Inputs: projectPath (required), scenePath (required), nodePath (required), saveScene.

scene-node-propertiesA

[compact alias of get_node_properties] Returns all properties of a specific node in a scene. Use to inspect current values before modifying. Returns property names, values, and types.

Inputs: projectPath (required), scenePath (required), nodePath (required), includeDefaults.

scene-nodesA

[compact alias of list_scene_nodes] Returns complete scene tree structure with all nodes, types, and hierarchy. Use to understand scene organization before modifying. Returns nested tree with node paths.

Inputs: projectPath (required), scenePath (required), depth, includeProperties.

scene-node-setA

[compact alias of set_node_properties] Sets multiple properties on a node in a scene. Prerequisite: scene and node must exist (use create_scene and add_node first). Use to modify position, scale, rotation, or any node-specific properties. Scene is saved automatically unless saveScene=false.

Inputs: projectPath (required), scenePath (required), nodePath (required), properties (required), +1 more.

scene-saveA

[compact alias of save_scene] Saves changes to a scene file or creates a variant at a new path. Most scene modification tools save automatically, but use this for explicit saves or creating variants.

Inputs: projectPath (required), scenePath (required), newPath.

script-createA

[compact alias of create_script] Creates a new GDScript (.gd) file with optional templates. Use to generate scripts for game logic. Templates: "singleton" (autoload), "state_machine" (FSM), "component" (modular), "resource" (custom Resource).

Inputs: projectPath (required), scriptPath (required), className, extends, +3 more.

script-infoA

[compact alias of get_script_info] Analyzes a GDScript and returns its structure: functions, variables, signals, class_name, extends. Use before modify_script to understand existing code.

Inputs: projectPath (required), scriptPath (required), includeInherited.

script-modifyA

[compact alias of modify_script] Adds functions, variables, or signals to an existing GDScript. Use to extend scripts without manual editing. Supports @export, @onready annotations and type hints.

Inputs: projectPath (required), scriptPath (required), modifications (required), reason.

signal-connectA

[compact alias of connect_signal] Creates a signal connection between nodes in a scene. Prerequisite: source and target nodes must exist. Use to wire up button clicks, collision events, custom signals. Saved to scene file.

Inputs: projectPath (required), scenePath (required), sourceNodePath (required), signalName (required), +3 more.

tool-catalogA

[compact alias of tool_catalog] Discover available tools including hidden legacy tools. Use query to search by capability keywords. Results include group categorization (core/dynamic). Matching dynamic groups are auto-activated and become available immediately. Core groups (always visible): core_meta, core_project, core_editor, core_scene, core_script, core_class, core_signal, core_resource, core_export, core_runtime, core_visualizer, core_diagnostics. Dynamic groups (on-demand): scene_advanced, uid, import_export, autoload, signal, runtime, resource, animation, plugin, input, tilemap, audio, navigation, theme_ui, asset_store, testing, dx_tools, intent_tracking, class_advanced, lsp, dap, version_gate.

Inputs: query, limit.

tool-groupsA

[compact alias of manage_tool_groups] Manage tool groups. Actions: list (show all core + dynamic groups), activate (enable a dynamic group), deactivate (disable a dynamic group), reset (disable all dynamic), status (show current state). Core groups (always visible, 33 tools): core_meta, core_project, core_editor, core_scene, core_script, core_class, core_signal, core_resource, core_export, core_runtime, core_visualizer, core_diagnostics. Dynamic groups (on-demand, 78 tools): scene_advanced, uid, import_export, autoload, signal, runtime, resource, animation, plugin, input, tilemap, audio, navigation, theme_ui, asset_store, testing, dx_tools, intent_tracking, class_advanced, lsp, dap, version_gate.

Inputs: action (required), group.

visualizer-mapA

[compact alias of map_project] Crawl the entire Godot project and build an interactive visual map of all scripts showing their structure (variables, functions, signals), connections (extends, preloads, signal connections), and descriptions. Opens an interactive browser-based visualization at localhost:6505.

Inputs: projectPath (required), root, include_addons.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 33 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes, especially with descriptive aliases. However, the large number of tools (33) and some overlap between output-related tools (dap-output, editor-debug-output, lsp-diagnostics) could cause minor confusion, though descriptions clarify the sources.

    Naming Consistency5/5

    All tool names follow a consistent lowercase-with-hyphens pattern (e.g., class-info, editor-run). No mixed conventions or irregular formats, making it predictable for an agent.

    Tool Count3/5

    33 tools is above the typical well-scoped range (3-15). While the breadth of Godot development justifies many tools, the count is borderline high and may overwhelm agents, despite the management tools (tool-catalog, tool-groups).

    Completeness4/5

    The toolset covers core Godot workflows: project, scene, script, class, export, runtime, debugging, and diagnostics. Minor gaps exist (e.g., no explicit file delete or node rename), but essential CRUD and lifecycle operations are present.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      An MCP server that gives AI assistants direct control over Godot 4 game development projects. It enables launching the editor, running projects, creating and editing scenes, writing GDScript, and inspecting assets through natural language commands.
      44
      4
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      An enhanced MCP server for interacting with the Godot game engine, enabling AI assistants to launch the editor, run projects, manage scenes and nodes, and handle scripts.
      16
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      This MCP server allows AI assistants to control the Godot editor and running games, enabling scene creation, script editing, input simulation, and gameplay testing through 174 tools.
      100
      443 npm
      1
      MIT