convez.ai
MCP ServerProdutividadeAvançado
MrBoostie

Godot MCP Enhanced

MrBoostie/godot-mcp-enhanced

MCP server para automação completa de desenvolvimento Godot com IA

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP aprimorado para Godot Engine que permite desenvolvimento de jogos assistido por IA em loop fechado. Oferece leitura/escrita de cenas e scripts, execução dinâmica de GDScript, screenshots, testes automatizados e gerenciamento completo de recursos do projeto diretamente via protocolo MCP.

Instalação

$npx convez-ai MrBoostie/godot-mcp-enhanced

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
2

Casos de uso

  • Desenvolvimento de jogos assistido por IA com iteração rápida
  • Automação de testes e validação de projetos Godot
  • Geração e edição de scripts GDScript via modelos de linguagem
  • Análise e manipulação de cenas e árvore de nós em tempo real

Veredito

Ferramenta robusta e madura que eleva significativamente a capacidade de automação e assistência de IA para desenvolvimento Godot. Superarquia de features em relação ao original, com suporte a execução de scripts, análise estruturada de erros e arquitetura dual (headless + WebSocket).

README

A tradução para o português deste README ainda está na fila.

Godot MCP Enhanced

Enhanced Godot Engine MCP Server — designed for AI-assisted game development closed loop. Based on the secondary development of godot-mcp, it fills the key capability gaps: scene reading, script reading and writing, screenshots, testing, dynamic GDScript execution, etc. English

Comparison with original godot-mcp

Featuresgodot-mcpgodot-mcp-enhanced
Launch EditorSupportSupport
Run ProjectSupportSupport (+ automatic timeout)
Get debug outputSupport (raw)Support (structured: error/warning/print classification)
Stop ProjectSupportSupport (+ summary)
Get versionSupportSupport
List ProjectsSupportSupport
Project InformationSupportSupport (+ File Statistics)
Create ScenariosSupportSupport
Add nodeSupportSupport
Loading WizardSupportSupport
Save sceneSupportSupport
Read scene (parse .tscn)Not supportedSupported
Read script (.gd)Not supportedSupported
Write script (.gd)Not supportedSupported
List files (with filtering)Not supportedSupported
Read project configurationNot supportedSupported
ScreenshotNot supportedSupported
Run unit tests (GUT)Not supportedSupported
Execute arbitrary GDScriptNot supportedSupported
Runtime scene tree queryNot supportedSupported
Deep Check NodeNot SupportedSupported
Add nodes in batchesNot supportedSupported
Project VerificationNot SupportedSupported
Resource ImportNot SupportedSupported
Run Verification + Scene Tree SnapshotNot SupportedSupported
Edit Script (Line Range Replacement)Not SupportedSupported
Autoload context executionNot supportedSupported
Structured Error AnalysisNot SupportedSupported
MCP resource (godot://)Not supportedSupported
Script syntax validationNot supportedSupported (file-by-file Godot parser check)
Version inconsistency detectionNot supportedSupported (project.godot vs binary version)
Search Replace EditNot SupportedSupported (search_and_replace, CRLF safe)
Automatically retry screenshotsNot supportedSupported (retry with 2x frameDelay after failure)
Audio playback controlNot supportedSupported (play/stop/parameter/status query)
TileMap EditNot supportedSupported (read and write/fill/copy-paste/transform, compatible with old versions of TileMap and TileMapLayer)
Dual-mode architectureNot supportedSupported (Headless CLI + Editor WebSocket JSON-RPC 2.0)
Particle SystemNot supportedSupported (GPU particle creation/emission/processing/presets/materials, 6 preset effects)
Navigation systemNot supportedSupported (NavigationRegion3D/Agent/Link creation and management)
AnimationTreeNot supportedSupported (state machine/hybrid tree/hybrid space creation and management)
Test AssertionNot SupportedSupported (Scenario Tree Assertion + Stress Test)
Export ManagementNot SupportedSupported (Default Query/Export Build)
Materials and ShadersNot supportedSupported (read and write materials/shader editors/templates)
Game BridgeNot supportedSupported (runtime query/input/wait)
Workflow engineNot supportedSupported (dev_loop/scenario snapshot/batch verification)
Animation player controlNot supportedSupported (query/play/edit animation)
Performance AnalysisNot SupportedSupported (FPS/Memory/Draw Call/Physical Statistics)
3D spatial queryNot supportedSupported (transform/AABB/bounds/area search)

Core Highlights

Dual-mode architecture

v0.8.0 introduces a dual-mode architecture, supporting both Headless CLI and Editor WebSocket two connection methods:

  • Headless mode (legacy): Execute code in a separate Godot process via executeGdscript(), all tools continue to support
  • Editor mode (new): Connect the GDScript plug-in in the editor through WebSocket JSON-RPC 2.0 to operate the opened scene in real time
  • Editor plug-in: addons/godot_mcp_server/ provides command_handler + 7 command modules (node/test/export/particle/nav/animtree/undo)
  • Automatically detect the editor connection status, and the two mode tools do not conflict with each other

Dynamic GDScript execution

The execute_gdscript tool allows AI to execute arbitrary GDScript code in headless mode:

  • Code Snippet Mode: No need to write extends, the entered code will be automatically packaged into a complete extends SceneTree script. Supports declarations such as func/var/const (automatically placed at the class level) and statement lines (placed in the _initialize() body)
  • Structured Output: Return key-value pair results through _mcp_output(key, value)
  • Timeout Control: Prevent code from getting stuck in an infinite loop
  • Autoload context: Setting load_autoloads=true can run in the complete project environment and access global singletons such as DataRegistry and PlayerData.
  • Structured Errors: Returns a errors array containing error type, file, line number, message and fix suggestions

Batch operations

batch_add_nodes adds multiple nodes in one call, and only does pack+save at the end to avoid starting and stopping headless Godot on each node, which significantly improves performance.

Project Verification

validate_project Static scan project, check:

  • A resource that does not exist is referenced in the .tscn file.
  • The preload()/load() path in the .gd script is invalid
  • The source resource has been deleted but the .import file remains

Resource import

import_resources scans the directory to batch register resources (pictures/audio/fonts/3D models) and automatically generates .import files.

Closed-loop development workflow

read_scene/read_script → understand structure → write_script → run_and_verify→ validate_project → batch_add_nodes → import_resources → Verification passed```

## Security Boundary
This tool runs in a trusted local development environment and has the following security features:
- **GDScript Dynamic Execution**: Tools such as `execute_gdscript` will execute arbitrary GDScript code in the local Godot process. GDScript has full system access (file reading and writing, network requests, process creation). **For use in trusted local development environments only, not exposed to untrusted remote connections. **
- **⚠️ The GDScript sandbox is only an anti-misoperation layer**: the built-in regex scanner can detect common dangerous patterns (such as `OS.execute`, `FileAccess.open(... WRITE)`), but can be bypassed through indirect methods such as string concatenation**. The sandbox is not a security boundary and is only used to prevent the AI ​​from accidentally calling dangerous APIs. For true sandbox isolation, use containers/VMs. Scanning can be turned off via `GODOT_MCP_SANDBOX=disabled`, or blocked operations allowed via `GODOT_MCP_ALLOW_UNSAFE=true`.
- **Path Whitelist**: Limit accessible project paths through the `ALLOWED_PROJECT_PATHS` environment variable (semicolon separates multiple paths). Allows all paths and prints a one-time warning when not configured, and can be used with zero configuration.
- **Confirmation Token**: Require explicit confirmation for dangerous operations (such as deleting nodes) to prevent AI misoperation.
- **Output tag anti-forgery**: Use a randomly generated tag string for each execution to prevent GDScript code from forging MCP output.
**Local use only**: This tool is designed for AI and developers to collaborate on the same machine and does not provide any remote access authentication or encryption mechanisms.
## Tool description language strategy
The tool's `description` and parameter descriptions are in Simplified Chinese, which is an intentional design decision:
- This project mainly serves the Chinese game developer community
- The AI model's ability to understand Chinese tool descriptions is equivalent to that of English
- If you need international support, please submit an Issue or PR
## Install
```bash
git clone https://github.com/MrBoostie/godot-mcp-enhanced.git
cd godot-mcp-enhanced
npm install

First time use

After connecting to the Godot project, it is recommended to run the following tool immediately to configure project rules with one click:

setup_project_rules(project_path="your project path")```

This will automatically generate:
- **`.claude/settings.json`**: PostToolUse hook, automatically prompts AI to run `validate_scripts` to verify syntax every time after editing `.gd` file
- **`CLAUDE.md`**: Project-level rules, including GDScript validation rules and release access control (`verify_delivery` check)
If there is an existing configuration that you want to update, use `force=true` to overwrite it. If only one of them is required, use `hooks=false` or `claude_md=false` to skip it.
## Configuration
### Cursor

Create `.cursor/mcp.json` in the project:
```json
{
  "mcpServers": {
    "godot": {
      "command": "node",
      "args": ["D:/GitHub/godot-mcp-enhanced/build/index.js"],
      "env": {
        "GODOT_PATH": "C:/path/to/godot.exe",
        "DEBUG": "true"
      }
    }
  }
}

Cline / Claude Code

Add to MCP settings:

{
  "mcpServers": {
    "godot": {
      "command": "node",
      "args": ["D:/GitHub/godot-mcp-enhanced/build/index.js"],
      "env": {
        "GODOT_PATH": "C:/path/to/godot.exe",
        "DEBUG": "true"
      },
      "autoApprove": [
        "launch_editor", "run_project", "stop_project",
        "get_debug_output", "capture_screenshot", "analyze_screenshot", "run_tests",
        "get_godot_version", "list_projects", "get_project_info",
        "list_files", "read_project_config", "create_project", "setup_project_rules",
        "read_scene", "create_scene", "add_node", "save_scene", "load_sprite",
        "edit_node", "remove_node", "batch_add_nodes",
        "read_script", "write_script", "edit_script",
        "generate_test", "create_test_scene", "project_replace",
        "query_scene_tree", "inspect_node",
        "validate_project", "import_resources",
        "run_and_verify", "analyze_error", "validate_scripts",
        "signal_connect", "signal_disconnect", "signal_emit", "signal_list",
        "physics_raycast", "physics_body_info", "diagnose_physics",
        "query_spatial", "collision_overlay", "node_create_3d", "nav_query_path",
        "audio_play", "audio_stop", "audio_set_param", "audio_query",
        "tilemap_read", "tilemap_set_cell", "tilemap_erase_cell", "tilemap_fill_rect",
        "tilemap_clear", "tilemap_copy", "tilemap_paste", "tilemap_set_transform",
        "material_read", "material_write", "shader_edit",
        "game_bridge_install", "game_bridge_uninstall",
        "game_query", "game_input", "game_wait",
        "dev_loop", "scene_snapshot", "batch_validate", "batch_create_files", "batch_run_verify",
        "animation", "profiler", "spatial_info",
        "get_class_info", "search_classes", "find_method", "get_inheritance",
        "test_assert", "test_stress", "export_list_presets", "export_get_preset", "export_build",
        "particles_create", "particles_set_emission", "particles_set_process",
        "particles_load_preset", "particles_set_material",
        "nav_create_region", "nav_bake_mesh", "nav_create_agent", "nav_set_params", "nav_create_link",
        "animtree_create", "animtree_add_state", "animtree_add_transition",
        "animtree_set_blend", "animtree_play",
        "ik_modifier_create", "ik_modifier_get", "ik_modifier_set", "ik_list_bones",
        "verify_delivery", "list_templates", "apply_template",
        "ui_create_control", "ui_build_layout", "ui_set_layout", "ui_get_layout",
        "ui_anchor_preset", "ui_set_theme", "ui_container_add", "ui_draw_recipe",
        "theme_create", "theme_set_property",
        "recording_start", "recording_stop", "recording_save", "recording_load", "recording_play",
        "editor_sync_start", "editor_sync_stop",
        "quick_scene", "diff_scenes", "detach_instance"
      ]
    }
  }

⚠️ Security Tip (A-07): The presence of high-risk tools such as execute_gdscript, write_script, edit_script, project_replace in the autoApprove list means that the AI ​​can execute arbitrary GDScript code and file modifications without confirmation. In security-sensitive projects, it is recommended that these tools be removed from autoApprove and confirmed manually instead. }```

Environment variables

| variable | description | default value ||------|------|--------| | GODOT_PATH | Godot executable file path | Automatic detection || GODOT_PROJECT_PATH | Specify Godot project path (skip automatic detection) | Automatic detection || GODOT_MCP_SEARCH_PATHS | Additional Godot binary search directories (semicolon separated) | — || DEBUG | Enable verbose logging | false || ALLOW_OUTSIDE_PROJECT_PATHS | Allow the tool to access files outside the project directory (such as screenshot output path) | false |

Tool list (140+)

Execution tool

| Tools | Instructions ||------|------| | launch_editor | Start Godot Editor GUI || run_project | Run the project in debug mode (automatic timeout) || stop_project | Stop the running project and return structured output || get_debug_output | Get classified debug output (error/warning/print) || capture_screenshot | Capture game screen (Windows default window mode, Linux/macOS automatically downgrades) || analyze_screenshot | AI analysis of screenshot content (element identification, defect detection) || run_tests | Run GUT unit tests and parse results || get_godot_version | Get Godot engine version |

Verification tool

| Tools | Instructions ||------|------| | run_and_verify | One-click headless execution and return of structured error/warning analysis. Supports capture_tree option while taking scene tree snapshots. Automatically detect version inconsistencies and script syntax errors. || analyze_error | Reanalyze Godot output text and provide repair suggestions || validate_scripts | Run the Godot parser file-by-file to verify GDScript syntax and detect Parse Errors that may be missed by the headless run |

Dynamic execution tool

| Tools | Instructions ||------|------| | execute_gdscript | Execute arbitrary GDScript code in headless mode. Supports code snippet mode (auto-wrapping) and complete class mode. Setting load_autoloads=true works in the full Autoload context (DataRegistry, PlayerData, etc.). || query_scene_tree | Load the scene and query the runtime node tree, returning the actual attribute values ​​after parsing. || inspect_node | Depth inspection node: all attributes, signal connections, sub-nodes, supports recursive depth control. |

Project Tools

| Tools | Instructions ||------|------| | list_projects | Search the directory for Godot projects || get_project_info | Project metadata + file statistics || list_files | List files (supports extension/subdirectory filtering) || read_project_config | Parse project.godot into structured JSON || create_project | Create a complete Godot project structure || setup_project_rules | One-click configuration of project rules (hooks + CLAUDE.md), recommended to run for the first time || validate_project | Check for missing resources, invalid script references, orphaned .import files || import_resources | Scan directories to batch generate .import files (pictures/audio/fonts/3D models) |

Scene tools

| Tools | Instructions ||------|------| | read_scene | Parse .tscn into node tree JSON || create_scene | Create new scene || add_node | Add nodes to the scene || batch_add_nodes | Add multiple nodes in one call (much faster than repeated add_node) || save_scene | Save scene changes || load_sprite | Load texture to sprite node || edit_node | Edit node attributes (position/scale/rotation/custom attributes) || remove_node | Remove node from scene (requires confirmation token) || quick_scene | Quickly create scenes + optional scripts (one step at a time) || instance_scene | Instantiate the .tscn scene to the target parent node || detach_instance | Detach instance node from scene tree || diff_scenes | Compare the differences between two .tscn scene files || merge_scene | .tscn conflict resolution (three-party merge, ExtResource/SubResource ID remapping) |

Script tool

| Tools | Instructions ||------|------| | read_script | Read .gd/.cs files (including metadata) || write_script | Write/overwrite .gd file || edit_script | Edit .gd files by line range. Supports raw/smart indentation mode, content verification, and comparison before and after changes. || generate_test | Analyze .gd files and generate GUT test scripts || create_test_scene | Create a GUT test runner scenario || project_replace | Full project batch search and replace (CRLF safe) |

Runtime operation tools

Note: Runtime operations only take effect in the headless execution context and are not persisted to .tscn files. If you need to persist scene modifications, please use add_node + save_scene. | Tools | Instructions ||------|------| | signal_connect | Signal connecting two nodes. Only affects the current execution context. || signal_disconnect | Disconnect the signal. Only affects the current execution context. || signal_emit | Emit node signals, parameters only support basic types (string/number/bool/null). Only affects the current execution context. || signal_list | Lists the signals available on the node. || physics_raycast | Perform 3D ray detection and return collision point, normal, and collision body information. || physics_body_info | Get the collision shape, AABB, collision layer/mask information of the physical body. || node_create_3d | Create 3D nodes at runtime (supports 16 whitelisted types). Headless creation is not persistent. || nav_query_path | Query the 3D navigation path, support specifying NavigationRegion3D or automatically fall back. |

Audio playback control tool (runtime)

Note: Runtime operations only take effect in the headless execution context and are not persisted to .tscn files. | Tools | Instructions ||------|------| | audio_play | Play audio resources. Supports three node types: AudioStreamPlayer, AudioStreamPlayer2D, and AudioStreamPlayer3D. || audio_stop | Stops the specified audio player from playing. || audio_set_param | Set audio parameters: volume in dB, pitch scaling, bus routing. || audio_query | Query the playback status (playing/paused/stopped), current playback position, and bus information. || diagnose_physics | Diagnose physics body collision status (including ConcavePolygonShape3D trap detection). || query_spatial | Spatial area query: Collider distance sorting, supporting collision mask filtering. || collision_overlay | Create a collision shape colored wireframe overlay (StaticBody=blue/CharacterBody=green/RigidBody=red/Area=yellow). |

TileMap editing tool (runtime)

Note: Runtime operations only take effect in the headless execution context and are not persisted to .tscn files. To persist TileMap modifications, please use execute_gdscript to write to .tscn or operate in the editor. Supports both TileMap (old version) and TileMapLayer (Godot 4.3+ new version) node types. | Tools | Instructions ||------|------| | tilemap_read | Read the cell data of TileMap/TileMapLayer and return the tile coordinates, source_id, atlas_coords, and alternative_tile in the specified area. || tilemap_set_cell | Set the source atlas and coordinates of a single tile. || tilemap_erase_cell | Erase a single tile (set to empty). || tilemap_fill_rect | Batch fill all tiles in the rectangular area. || tilemap_clear | Clear all tiles of TileMap/TileMapLayer. || tilemap_copy | Copy the specified area as a template (internal cache) for subsequent pasting. || tilemap_paste | Paste the copied template into the destination location. || tilemap_set_transform | Set the flip/rotation transformation (horizontal flip, vertical flip, Transpose) of the tile. | All runtime tools support the optional load_autoloads parameter (default true) to execute in the full Autoload context.

API Documentation Tool

| Tools | Instructions ||------|------| | get_class_info | Get the methods, attributes, signals, and constants of the class || search_classes | Search for classes by name/description || find_method | Find method details (including inheritance chain) || get_inheritance | Get the complete inheritance chain |

Material and Shader Tools (Runtime)

Note: Runtime operations only take effect in the headless execution context and are not persisted to .tscn files. | Tools | Instructions ||------|------| | material_read | Read node material attributes and shader uniform list || material_write | Set material parameters, create/attach/save materials (.tres) || shader_edit | Read and write shader code, load .gdshader, apply templates, compile diagnostics |

Game Bridge Tools

| Tools | Instructions ||------|------| | game_bridge_install | Install MCP Bridge autoload to the project (WebSocket server) || game_bridge_uninstall | Uninstall MCP Bridge autoload || game_query | Query the running game status (scene tree/node attributes/performance/viewport) || game_input | Send input events (keyboard/mouse/text) to the running game || game_wait | Wait for specific game state conditions (nodes appear/attribute values ​​change) |

Workflow Tools

| Tools | Instructions ||------|------| | dev_loop | Development cycle: execute GDScript → verify → capture output, support save_state file as memory || scene_snapshot | Scene tree snapshot, used for before and after comparison to detect changes || batch_validate | Batch verification of multiple GDScript files |

Animation tools (runtime)

| Tools | Instructions ||------|------| | animation | Query, play, and edit animations. Supports list_players, get_info, get_details, get_keyframes, play, stop, seek, create, delete, update_props, add/remove_track, add/remove/update_keyframe and other sub-operations |

Performance analysis tools (runtime)

| Tools | Instructions ||------|------| | profiler | Performance analysis: snapshot (FPS/memory/draw call/physical statistics), sampling analysis, active process detection, signal connection audit |

3D Space Tools

| Tools | Instructions ||------|------| | spatial_info | Get Node3D spatial information: transform, AABB, bounds, area search |

Testing and exporting tools

| Tools | Instructions ||------|------| | test_assert | Assert scene tree status: node_exists, property_equals, signal_connected, node_count || test_stress | Stress test: repeatedly create/destroy nodes to detect memory leaks || export_list_presets | List project export presets || export_get_preset | Get export preset details || export_build | Execute export build |

Particle system tools (runtime)

Note: Runtime operations only take effect in the headless execution context and are not persisted to .tscn files. | Tools | Instructions ||------|------| | particles_create | Create GPU particle nodes (GPUParticles2D / GPUParticles3D) || particles_set_emission | Set emission parameters: shape (point/sphere/box/ring), radius, direction, diffusion || particles_set_process | Set processing parameters: gravity, speed, explosiveness, life cycle, damping || particles_load_preset | Load preset effects: fire / smoke / rain / snow / sparkle / explosion || particles_set_material | Create or reset ParticleProcessMaterial |

Navigation tools (runtime)

Note: Runtime operations only take effect in the headless execution context and are not persisted to .tscn files. | Tools | Instructions ||------|------| | nav_create_region | Create a NavigationRegion3D and optionally bake the navigation mesh || nav_bake_mesh | Baking navigation mesh (long operation) || nav_create_agent | Create NavigationAgent3D and set pathfinding parameters || nav_set_params | Set navigation agent parameters (10 configurable fields: radius, height, max_speed, etc.) || nav_create_link | Create NavigationLink3D connection point (supports bidirectional) |

AnimationTree tools (runtime)

Note: Runtime operations only take effect in the headless execution context and are not persisted to .tscn files. | Tools | Instructions ||------|------| | animtree_create | Create AnimationTree node (supports AnimationNodeStateMachine / BlendTree / BlendSpace2D) || animtree_add_state | Add animation state to state machine (AnimationNodeAnimation) || animtree_add_transition | Add transitions between states (including crossfade time and conditions) || animtree_set_blend | Set blending parameters (float for BlendTree, Vector2 for BlendSpace) || animtree_play | Switch to target state (via playback.travel) |

IK Framework Tools (Runtime)

| Tools | Instructions ||------|------| | ik_modifier_create | Create IK modifier node (TwoBoneIK3D / FABRIK3D / CCDIK3D / SplineIK3D / JacobianIK3D) || ik_modifier_get | Read IK modifier properties || ik_modifier_set | Set IK parameters (active, influence, bone_name, target, magnet) || ik_list_bones | List Skeleton3D bones |

Verification Delivery Tool

| Tools | Instructions ||------|------| | verify_delivery | End-to-end delivery verification: scene tree integrity + script health + performance + custom assertions + GDD standards compliance |

Game Design Tools

| Tools | Instructions ||------|------| | validate_gdd | Verify that the game design document meets the 8-chapter criteria (Overview, Player Fantasy, Detailed Rules, Formulas, Edge Cases, Dependencies, Tuning Knobs, Acceptance Criteria) || chain_verify | Chain-of-Verification Self-Doubt Engine: Generates 5 challenging questions for review conclusions to prevent blind spots and overconfidence |

Code template tool

| Tools | Instructions ||------|------| | list_templates | List available code templates (built-in + user-defined) || apply_template | Apply code template to specified script (supports variable substitution) |

UI layout tools (runtime)

| Tools | Instructions ||------|------| | ui_create_control | Create UI Control node || ui_build_layout | CSS Flexbox/Grid translation layer that builds Godot Container trees from declarative layout descriptions || ui_set_layout | Set Control node layout properties (anchor/offset/minimum size) || ui_get_layout | Query Control node layout information || ui_anchor_preset | Apply anchor point presets (full_rect/center/top_wide, etc. 16 types) || ui_set_theme | Set/Create/Save/Load Theme || ui_container_add | Add child Control node to Container || ui_draw_recipe | Declarative drawing operations (rect/circle/line/arc/polygon/string) || theme_create | Create an empty Theme or extract a Theme from a node || theme_set_property | Set Theme attribute (font/color/constant/stylebox) |

Recording tool

| Tools | Instructions ||------|------| | recording_start | Start recording input events (keyboard/mouse) || recording_stop | Stop recording and return event data || recording_save | Save recording to JSON file || recording_load | Load recording file || recording_play | Playback recorded input events |

Editor synchronization tool

| Tools | Instructions ||------|------| | editor_sync_start | Start scene tree real-time monitoring (push node_added/node_removed event) || editor_sync_stop | Stop scene tree monitoring |

MCP Resources (Resources)

AI clients can discover and read project context via the godot:// URI scheme without explicit tool calls.

Static resources

| URI | Description ||-----|------| | godot://project/info | Project metadata + file statistics (JSON) || godot://project/config | Original project.godot file |

Resource Template

| URI pattern | Description ||----------|------| | godot://scene/{path} | Read .tscn scene as node tree summary || godot://script/{path} | Read .gd script file || godot://file/{path} | Read any text file in the project |

Security restrictions

  • The path must be in the project root directory (../ traversal is prohibited)- .godot/, .import/, node_modules/ directories blocked- .import, .uid, .godot file extensions blocked

Usage examples

Client: ListResources → Discover all scenes and scripts
Client: ReadResource("godot://project/info") → project configuration + statistics
Client: ReadResource("godot://scene/scenes/main.tscn") → Node tree summary
Client: ReadResource("godot://script/scripts/player.gd") → GDScript source code```

## Closed-loop development example
  1. AI: read_scene("scenes/player.tscn") → Get the complete node tree and understand the scene structure
  2. AI: read_script("scripts/player_controller.gd") → Read the current code and determine what needs to be modified
  3. AI: write_script("scripts/player_controller.gd", updated_code) → Write changes
  4. AI: run_and_verify(project, capture_tree=true) → headless running + error analysis + scene tree snapshot
  5. AI: validate_project(project) → Check for missing resources and invalid references
  6. AI: batch_add_nodes(project, scene, nodes=[...]) → Add multiple UI elements at once
  7. AI: import_resources(project, directory="assets/ui") → Register new resources to the project
  8. If you still have problems → go back to step 2```

Acknowledgments

  • godot-mcp — original project- Hastur Operation Plugin — Inspiration for dynamic GDScript execution and structured output- Claude Code Game Studios — Draws on the following functional concepts:- Hooks + Rules system → setup_project_rules automatically generates .claude/settings.json (PostToolUse hook automatically verifies GDScript) and CLAUDE.md (project coding standards)- Gate-check/verify → verify_delivery End-to-end delivery verification (scenario tree integrity + script health + performance + custom assertions + GDD compliance)- Workflow pipeline → dev_loop execution → verification → screenshot integrated workflow, supporting acceptance acceptance criteria and save_state session memory- GDScript Lint → validate_scripts file-by-file syntax verification (L015 line-level scanning + string/comment filtering), benchmarked against CCGS's validate-commit.sh- GDD standard → validate_gdd 8 chapters game design document structure verification, benchmarked against the design/gdd path rules of CCGS- Chain-of-Verification → chain_verify Self-questioning engine to prevent censorship blind spots- Code Template → list_templates / apply_template template system, benchmarked against the 41 document templates of CCGS

System requirements

  • Godot Engine 4.x (tested 4.6+)- Node.js >= 18
  • GUT plugin (for run_tests tool)

Screenshot function platform description

capture_screenshot tools use different rendering strategies depending on the platform: | Platform | Mode | Description ||------|------|------| | Windows | Window mode (default) | The viewport texture returns null in Headless mode, and the GPU context must be used || Linux | Headless → window mode downgrade | Headless + OpenGL3 depends on whether the GPU driver supports it || macOS | Headless → window mode downgrade | Same as Linux | The built-in screenshot_capture.gd uses the process_frame signal mode and call_deferred() to ensure reliable scene loading and frame capture.

License

MIT

Update log

See CHANGELOG.md for the complete change record. | Version | Date | Key Points ||------|------|------| | v0.17.0 | 2026-06-07 | Review fixes 9 (4C+5I/A) — tscn editing correctness + confirm token truncation protection + string UID + security hardening, 2023 testing || v0.16.0 | 2026-05-31 | Review-driven quality improvement — ToolDispatcher extraction + 87 commits + merge_scene + project scaffolding + smart type conversion + 1638 tests || v0.15.1 | 2026-05-27 | Godot 4.6 editor plugin compatibility fixes || v0.15.0 | 2026-05-27 | 6-agent parallel review (14 CRITICAL fixes) + deny-by-default security + Bridge recording + ESLint + 1509 tests || v0.14.0 | 2026-05-24 | 7-axis full-dimensional review (8 CRITICAL fixes) + IK framework MVP + Vitest migration 1257 tests || v0.13.0 | 2026-05-23 | Bridge security hardening 20 items + requestId modulo + CSS Grid + EditorConnection reconnection limit || v0.12.0 | 2026-05-23 | Iterative URL decoding to prevent path traversal + verify_delivery 4-dimensional verification + dev_loop acceptance || v0.11.1 | 2026-05-22 | Bridge TCP binding 127.0.0.1 + key file deleted after reading + opsErrorResult isError repair || v0.11.0 | 2026-05-22 | CSS Flexbox layout translation layer + GDScript Lint rule engine + path traversal protection enhancement || v0.10.1 | 2026-05-21 | Bridge TCP binding local address + key file life cycle management + opsErrorResult fix || v0.10.0 | 2026-05-19 | Scene instantiation + editor real-time synchronization + code optimization and reconstruction (124 tools) || v0.9.0 | 2026-05-16 | Batch Tools + UI Tools + Recording System + Confirmation Token + Read-Only/Lite Mode (118 Tools) || v0.8.0 | 2026-05-13 | Dual-mode architecture + test framework + particle/navigation/AnimationTree (96 tools) || v0.7.0 | 2026-05-08 | Security hardening + input escaping + type safety + tscn-parser repair || v0.6.0 | 2026-05-03 | Audio Playback Control 4 Tools + TileMap Editing 8 Tools || v0.5.0 | 2026-05-02 | Signal Control + Physical Query + 3D Creation + Navigation Pathfinding (8 Tools) || v0.4.0 | 2026-05-01 | Version detection + validate_scripts + search_and_replace + screenshot stability || v0.3.0 | — | edit_script + batch_add_nodes + validate_project + import_resources | | v0.2.0 | — | read_scene + read/write_script + query_scene_tree + MCP Resources | | v0.1.0 | — | Project management + scene operation + execution control + screenshot + execute_gdscript |

Ver o original no GitHub

Bom para

Relacionados