godot-mcp

Add a node to an existing scene file. Supports an optional script attachment, group memberships, and a tree of children created in the same call (1 tool call instead of N). Children format: {name|node_name, type|node_type, properties?, script?, groups?, children?}. Both key styles are accepted so children can reuse the same keys you use at the top level (node_name, node_type) or the shorter form (name, type). Unknown child keys are rejected with a clear error. **Atomic pre-validation:** the entire spec (top-level node + every descendant in `children`, recursively) is walked and validated BEFORE the .tscn is loaded from disk. Property names are checked against ClassDB + the attached script's @export'd properties; `script` paths are checked for existence and Script-ness; node_types are checked against ClassDB. If anything fails, returns `ok: false` with `validation_errors: [...]` listing every issue with path-pointed prefixes (e.g. `children[2].properties.text: property does not exist on Sprite2D`), and ZERO mutation. Previously a typo like `properties: {color: ...}` on a Sprite2D would be silently swallowed; now it surfaces immediately.

Attach or change a script on a node in a scene.

Run an ordered list of MCP tool calls as a single composite operation. Use this whenever you would otherwise issue multiple consecutive mutations on the same scene/script/project — e.g. "create a node, set 5 properties, attach a script, connect 2 signals" becomes one call instead of 9. Cuts round-trip latency, response tokens, and per-call error handling. The whole batch lands as ONE undo entry, so a single `mcp_undo` reverts everything. Modes: • atomic=true (default): on any failure, every earlier successful step is rolled back from snapshots before returning. The batch either fully applies or appears never to have happened. • atomic=false, stop_on_error=true (default): stop at first failure; successful steps are committed as a partial entry that mcp_undo can revert. • atomic=false, stop_on_error=false: run every command regardless; commit whatever succeeded. Each command is `{name: <tool>, args: <object>}`. Sub-commands run in order and reuse the normal tool dispatch path (same validation, same error shape). Disallowed inside a batch: `batch_execute` (no nesting), `mcp_undo` / `mcp_redo` / `mcp_undo_history` (would corrupt the in-progress entry), `wait` (coroutine), `run_scene` / `stop_scene` (process lifecycle isn't snapshotable). Read-only tools (read_scene, get_node_properties, etc.) are fine to include. Response: `{ok, atomic, stop_on_error, succeeded, total, results: [{ok, name, result}], failed_at?, failed_command?, error?, failures?, rolled_back?, rollback_errors?, undo_entry_id?}`. `results` length is `succeeded + failures.length` (early-broken batches stop after the first failure, so `results.length` can be less than `total`). The top-level `failed_at` / `failed_command` / `error` always describe the FIRST failure; `failures: [{index, name, error}]` lists EVERY failure (only relevant when atomic=false, stop_on_error=false, where multiple sub-commands can fail).

Invoke any method on any node, in either the editor's on-disk scene or the running game. The write counterpart to query_runtime_node (which only reads). **Two modes** controlled by `runtime`: • `runtime: false` (default, editor mode) — Loads the .tscn from disk, finds the node, invokes the method, ALWAYS saves the scene back. Snapshot taken so `mcp_undo` reverts the file. Use for **engine/built-in methods that mutate persistent scene state**: `CollisionObject2D.set_collision_layer_value(layer, on)`, `Curve2D.add_point(pos)`, `Node.add_user_signal(name)`, `Node.add_to_group(name, true)` (the `true` is required to persist into the .tscn). ⚠️ **Editor mode cannot run user-defined methods in non-@tool scripts.** Godot's editor instantiates scenes with `GEN_EDIT_STATE_MAIN`, which attaches scripts and lets `@export` vars round-trip but does NOT dispatch user method bodies for non-@tool scripts. `call_method` detects this case and refuses with `reason: "non_tool_script_method"` — DO NOT use editor mode to invoke `take_damage`, `respawn`, `play_intro`, or any other game-logic method on your script. Use runtime mode for that. • `runtime: true` — Routes the call to the MCPRuntime helper inside the running game. Finds the live node in the active SceneTree, invokes the method, returns the serialized result. Use to drive the game from the AI: `Player.take_damage(50)`, `AnimationPlayer.play("intro")`, `AudioStreamPlayer.play()`, `Inventory.add_item("sword", 1)`. REQUIRES `run_scene` first (the game must be running) — same precondition as query_runtime_node / send_input. **node_path resolution:** • editor mode — relative to scene root, e.g. "Player" or "UI/HUD/HealthLabel", or "." for root. • runtime mode — absolute ("/root/Main/Player") OR relative to current_scene ("Player"). Same rules as query_runtime_node. **args** — array of positional arguments. Each follows the same form as `modify_node_property.value`: primitives (`1.5`, `"hello"`, `true`, `null`), arrays, or `{type:"Vector2",x,y}` / `{type:"Color",r,g,b,a}` / `{type:"NodePath",...}` / `{type:"Resource",path:"res://..."}` discriminated objects. **Method validation** — on miss, returns `closest_matches` (top similar method names) and an `available_methods_sample` so the AI can self-correct. Arity is also pre-checked against `MethodInfo` (with default-arg awareness). **Destructive denylist** — `queue_free`, `free`, `set_script`, `remove_child`, `replace_by`, `reparent` require `confirm: true`. In runtime mode, calls directly on `/root/<name>` (likely autoloads or the active scene root) also require confirm. Use `attach_script` / `detach_script` / `remove_node` instead of the corresponding raw method calls in editor mode. **Coroutines** — methods containing `await` return a `GDScriptFunctionState`. Such calls are dispatched fire-and-forget: `is_coroutine: true, awaited: false` is reported, side effects still run, but the return value is not captured. Follow up with `wait` + `query_runtime_node` to observe results. **Return shape (success):** `{ok:true, runtime, scene_path?, node_path, node_class, method, method_signature?, duration_ms, return_value?, return_type?, awaited, is_coroutine}`. `awaited` and `is_coroutine` are ALWAYS present (stable for parsing). `return_value` / `return_type` are omitted when `expect_return: false` or the method is a coroutine. Object/Node returns are serialized as `{type:"Object", class, name?, node_path?, serializable:false}` — follow up with `query_runtime_node` to inspect properties. Resource returns are `{type:"Resource", class, resource_path?}`.

Query Godot's ClassDB for class information: properties, methods, signals, and inheritance. Use this to verify that a class, method, or property actually exists in the running Godot engine before writing code. Prevents using wrong method names, outdated Godot 3 API, or incorrect signatures.

Mark the current position in the Godot editor log. Subsequent get_console_log and get_errors calls will only return output after this point.

Close open editor tabs (scenes and/or scripts). Files on disk are NOT touched — this only changes the editor UI state. Default behavior with no args closes EVERY open tab (both scenes and scripts). Primary use case: test automation — reset the editor to a known state between test runs without restarting Godot. Also useful before calling delete_file / delete_folder, which refuse by default when the target is open in an editor tab. Filter by kind ("scene", "script", "any") and/or by specific paths. Paths can be given with or without "res://". SCENES: built on EditorInterface.close_scene() (Godot 4.5+). Unsaved changes are DISCARDED silently (matches Godot's native close-tab behavior); save first via the editor or save_resource_to_file if you need to preserve pending edits. SCRIPTS: Godot does not currently expose a public API to close script tabs from script. Requested script paths are returned in `scripts_closed_not_supported` with the reason rather than silently skipped. Workarounds: close manually via the X on the tab, or use `force=true` on the next file mutation to bypass the editor-open guard. Response: {ok, scenes_closed, scripts_closed_not_supported, not_open, remaining_scenes, remaining_scripts, message}. `scenes_failed` appears with per-path Godot error codes when any close fails.

Add, remove, or replace input actions and their key/button bindings. Use get_input_map to see current actions before modifying.

Connect a signal between two nodes inside a .tscn scene file. The target script must define the method (will refuse otherwise). Equivalent to clicking the "+" in the editor's Node > Signals panel and persists the connection to the .tscn. NOTE: scripts must be attached via attach_script (NOT via modify_node_property), otherwise the editor's in-memory node will not see the script and this tool will reject the connection.

Create a directory (with parent directories if needed).

Create a new Godot scene (.tscn) file with nodes. Use this to create player scenes, UI screens, game objects, etc. **Atomic pre-validation:** the entire spec (root, attach_script, every entry of `nodes`, and recursively their `children` / `properties` / `script`) is walked and validated BEFORE the scene file is created. If any node_type isn't a known class, any property name doesn't exist on its target class (plus the attached script's @export'd properties when present), or any script path is missing / isn't a Script — the call returns `ok: false` with a `validation_errors` array of path-pointed messages (`nodes[1].children[2].properties.text: property does not exist on Sprite2D`) and ZERO filesystem mutation. Fix all listed issues in one shot.

Create a NEW GDScript file (.gd) that does not exist yet. STRICTLY for .gd files — non-.gd extensions (.json, .gdignore, .md, etc.) are rejected with a pointer at write_file. A missing extension is auto-completed to .gd. Use edit_script for changes to an existing file. Use classdb_query to verify unfamiliar Godot class methods. After creating a script, consider run_scene and get_errors to verify it parses and behaves.

Permanently delete a file from the project. REQUIRES confirm=true as an explicit safety gate — omitting confirm returns an error. Creates a .bak backup alongside the original by default (disable with create_backup=false). REFUSES if the file is currently open in the editor (any scene tab or script editor tab); close the tab first, or pass force=true to bypass the check (not recommended — deleting the active scene out from under the editor can crash Godot). Use ONLY when deletion is explicitly requested; NEVER as a way to "edit" or "reset" a file (use edit_script instead). Does not delete directories.

Recursively delete a directory and ALL of its contents from the project. REQUIRES confirm=true. For a non-empty folder you must ALSO pass recursive=true — otherwise the call refuses and reports the file/sub-folder count. The whole deletion lands as a SINGLE undo entry: one mcp_undo restores every file (empty sub-directories are not restored — only files are tracked). Three safety guards each REFUSE rather than half-delete: (1) refuses if any file inside is open in an editor tab — close the tabs or pass force=true (deleting an open scene can crash Godot); (2) refuses if any external file contains a literal "res://..." string pointing into this folder (preload, ext_resource, FileAccess.open targets, autoload entries — see below) — repoint them or pass force_orphan=true (leaves broken references); (3) refuses if the contents are too large to snapshot for undo without evicting existing undo history — pass allow_no_undo=true to delete without an undo entry. Refuses to touch res:// root or the godot_mcp addon. For a single file use delete_file instead. Returns {ok, path, deleted_files, deleted_count, removed_dirs, total_bytes, undo_available, message} and, on partial failure, partial:true with delete_errors. REFERENCE-SCAN BEHAVIOR (important): The external-reference guard does a literal substring search for "res://" path strings across .tscn / .tres / .gd / .cs / .gdshader / project.godot. It is intentionally conservative — any literal path-string match counts, including runtime FileAccess.open() targets that you may consider safe to delete (the script will just re-create the file on its next run). The scanner cannot statically distinguish load-bearing references from benign strings. If the referenced list looks like runtime/regenerable targets, pass force_orphan=true rather than trying to fight the scan. FRESHLY-CREATED FILES: If you are deleting a folder containing files you just wrote in this session (via create_script etc.), Godot may not have written the auto-generated .uid sidecars yet, and they would be missed by the undo snapshot. Call rescan_filesystem before delete_folder when full undo fidelity matters.

Remove a script from a node in a scene.

Remove a signal connection from a .tscn scene file. No-op if the connection doesn't exist.

Edit an existing GDScript (.gd) file in place by replacing one snippet with another, and save. Snippets can be any size — a single line, a function, or the whole file for a full rewrite. If old_snippet matches more than once, pass context_before/context_after to disambiguate; if it can't be found, read_file the relevant range and retry with an exact match. ONLY for .gd files; not for .tscn scene files (use the scene/node tools). After editing, consider validate_script and run_scene + get_errors.

Search a .tscn file for nodes matching one or more filters. Filters AND together; pass any subset. Scene-scoped — for project-wide text search use search_project instead. Returns one entry per match with path (relative to scene root, "." = root), name, type (Godot class), and groups. Filters: • name_pattern: case-insensitive. If it contains "*" or "?" it is treated as a glob (matchn); otherwise as a substring (findn). • type: Godot class name (e.g. "Node2D", "CharacterBody3D", "Button"). Matches the node's class AND any subclass (so "Node2D" matches "Sprite2D"). Also matches custom script class_names registered globally via "class_name". Unknown types return an error (not silent zero matches). • in_group: exact group name; matches nodes where is_in_group() returns true. • recursive (default true): when false, only the scene root and its direct children are checked. If scene_path is omitted, defaults to the currently edited scene in the editor (must be saved at least once). Loads from disk like all other scene tools, so unsaved in-editor edits are not seen. No filters at all returns every node in the scene — handy as a structured alternative to scene_tree_dump.

Render an SVG to a PNG asset on disk via Image.load_svg_from_buffer. The SVG is rendered directly from bytes — no temp file is created, so concurrent calls are safe and project-rename quirks (user:// rebinding) cannot break it. Returns resource_path, absolute_path, dimensions {width,height}, and the render_scale used.

Return named 2D/3D physics collision layers from ProjectSettings.

Return the latest lines from the Godot editor Output panel (editor-side messages plus prints from the running game). NOTE: this does NOT include the Debugger > Errors tab — runtime push_error / script errors during play often surface only there. After run_scene, always call get_errors (not just this) to check for errors. When this tool finds error-prefixed lines it returns errors_detected=true and a hint pointing to get_errors. The tool also reads the Output panel's Info/Warning/Error filter buttons; if Info is OFF and prints appear missing, the response includes output_panel_filters and a hint asking the user to toggle Info back on (the panel filters its RichTextLabel, so missing-print symptoms are usually a UI toggle, not a tool bug). Pass debug:true to also include editor_log_rtl_path, editor_log_candidates (every EditorLog widget found, with sample tails), and output_panel_filters even when nothing looks suspicious.

Return the node path(s) the user has currently selected in the Godot editor (Scene dock). **Call this FIRST whenever the user refers to a node without naming a path** — phrases like "this node", "fix this", "change the color here", "delete that", "make this red", "the selected one", "what I have selected", etc. Returns an empty `selection` array if nothing is selected; that's informational, not an error. Selection is editor UI state (not stored in the .tscn) and is scoped to the currently edited scene tab — instances from a non-active tab will not appear. Response shape: `{ok, scene_path, selection: [{path, name, type}], count, reason, message?}`. `reason` is a stable machine-readable enum — `"ok"` (something is selected), `"none_selected"` (scene open but no nodes selected), or `"no_scene_open"` (no scene tab open at all) — so the agent can branch without string-matching the human-readable `message`. Paths are scene-relative ("." = scene root, "UI/HUD/Label" for nested) and match the format produced by `find_nodes` and `scene_tree_dump`, so they can be passed directly to `modify_node_property`, `set_node_properties`, `attach_script`, `remove_node`, etc. See the `selection-workflow` guide for end-to-end patterns.

Get errors and warnings from both the Godot Output panel and the Debugger > Errors tab. Returns file paths, line numbers, severity, stack traces, and which source each error came from. Debugger rows can appear a few frames after run_scene returns; pass wait_ms:300 when checking immediately after launch. If errors mention a missing method or property, use classdb_query to verify the correct API before fixing.

Check if Godot editor is connected to the MCP server.

Read a short markdown guide from the server. Same content as the MCP resources/read protocol, exposed as a tool so it works in MCP clients that do not support resources (e.g. Claude Desktop, Cursor chat). Call with no args to list available guides: testing-loop, scene-editing, asset-generation, troubleshooting, batching, selection-workflow, tool-index. Call with {slug: "..."} to get the full markdown. Useful when a workflow is non-obvious (testing a running game, choosing between scene-editing tools, troubleshooting "Runtime helper not connected", etc.).

Return the full InputMap: built-in actions (ui_*, spatial_editor/*) plus all project-defined actions from project.godot. Each action maps to an object with "events" (array of key/mouse/gamepad bindings) and optionally "deadzone". Use this before configure_input_map to see current bindings and deadzones.

Read the list of groups a node belongs to in a .tscn scene file.

Get available properties for a Godot node type. Use this to discover what properties exist on a node type (e.g., anchors_preset for Control, position for Node2D).

Query computed 3D spatial data for a Node3D in a scene file. Returns local/global positions, scales, rotation quaternions, and subtree bounding boxes (AABB) when available. Use this before making precise 3D placement decisions.

Snapshot of Godot's Performance singleton from inside the RUNNING game: fps, frame/physics step times, static memory (current + peak), renderer draw calls / objects / primitives, and engine-wide object/node/orphan counts. REQUIRES the game to be running with the MCPRuntime autoload connected (run_scene with wait_for_runtime=true first). Use when: 1. After run_scene — verify the scene actually hits its target fps before reporting "done". 2. The user reports lag/jank — localize the bottleneck (low fps vs high draw_calls vs growing memory vs orphan_nodes leak). 3. Before/after an optimization change — measure both sides to confirm the change helped (the optimization claim is only credible with numbers). Response fields: • fps, frame_time_ms — overall frame budget. Target is usually 16.67ms (60fps) or 8.33ms (120fps). • physics_process_time_ms — physics step time (cost per tick). • physics_ticks_per_second — configured tick rate (Engine.physics_ticks_per_second). Compare against physics_process_time_ms: if step time > 1000/tick_rate, physics is over budget. • static_memory_mb / _bytes, static_memory_peak_mb / _bytes — current and high-water mark. • draw_calls, objects_in_frame, primitives_in_frame — render-side cost. • total_objects, nodes, orphan_nodes — engine-wide instance counts. orphan_nodes > 0 means nodes were created without being added to the tree (memory leak smell). • custom_monitors (only when present) — any user-registered Performance.add_custom_monitor entries. Values reflect a single frame; sample twice with a wait in between if you need to confirm a trend.

Concise project settings summary: main_scene, window size/stretch, physics tick rate, and render basics.

Inspect ANY Godot Resource. Two modes: • path mode: pass {path: "res://foo.png"} for a resource on disk (.tres / .res / image / .glb / .ogg / .tscn / etc.) • node mode: pass {scene_path, node_path, resource_property} to inspect a resource attached to a node WITHOUT having to save it as .tres first (e.g. the shape on a CollisionShape2D, the material on a MeshInstance3D, the stream on an AudioStreamPlayer). Returns class, file size (path mode), and type-specific info: width/height for textures, vertex/surface counts and AABB for meshes, length for AudioStream/Animation, node count for PackedScene, common Material properties, Shape extents, and the resource's dependencies.

Return entries from the MCPRuntime in-game ring buffer. The buffer holds the last ~500 lines pushed via MCPRuntime.push_runtime_log(level, text) from your scripts plus internal connection events. For script prints/stdout use get_console_log; for runtime push_error / script errors use get_errors (it reads the Debugger > Errors tab — runtime errors do NOT appear in get_console_log). Returns entries with ts_ms, level, and text plus started_at_ms (when the helper started) and now_ms.

Combined editor + runtime status snapshot. Returns `playing`, `playing_scene`, `last_launched` ("current"|"main"|res-path), `uptime_ms` since the most recent run_scene, `runtime_helper_connected` (true once the in-game MCPRuntime autoload is talking to the MCP server), `godot_version` (e.g. "4.5.0.stable"), and `godot_version_info` (the full Engine.get_version_info() dict — `major`, `minor`, `patch`, `string`, `build`, `hex`, …). Useful for binding test reports to a specific Godot build without opening the About dialog.

Return the FULL property list of a single node in a .tscn file, including @export'd script vars and inherited properties — with current values, declared variant types, hint metadata, and a category grouping. Complements `read_scene` (which uses a curated subset of common properties for quick tree overviews) and `get_node_properties` (which returns class-level metadata, not a specific node's current values). Use this to verify a property was actually set after `add_node` / `set_node_properties` (especially for script @export vars), or to discover the exact name of a property you can't remember (handy when AI suggestions like "color" turn out to be "modulate"). Returns `{ok, scene_path, node_path, node_type, node_name, inheritance_chain, property_count, properties, categories}`.

Add an instance of another scene (.tscn) as a child node. This is how you compose scenes from reusable parts (like prefabs). The instance maintains a live reference to the source scene. Use this instead of add_node when you want to reuse an existing scene.

Compatibility shim: returns {playing, scene}. For richer info (uptime, runtime helper connectivity, last-launched target) prefer get_runtime_status.

List files and folders under a Godot project path (e.g., res://). Returns arrays of files and folders in the specified directory.

List all GDScript files in the project with basic metadata.

Browse Godot project settings by category. Returns values from the editor's in-memory state — this matches project.godot after a normal Godot save, but direct edits to project.godot on disk are not reflected until the editor restarts (rescan_filesystem does not help). Call without a category to see all available categories. Call with a category to see all settings with their current values, types, and valid options.

List signal connections involving a node. source="scene_file" (default) reads connections persisted to a .tscn. source="runtime" requires the game to be running and reads live connections from the SceneTree. Use the runtime mode to verify dynamically-connected signals (those connected from code in _ready, not in the editor).

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.

Re-apply the most recently undone MCP mutation(s). Use this proactively whenever you've over-undone — for example, you walked back several steps to inspect intermediate state, or you undid in error and want to recover the change without re-deriving its arguments. Also use when the user says "redo", "put it back", "never mind, do it again", or similar. Prefer this over re-issuing the original tool call — it restores the exact post-mutation state with no guessing. After mcp_undo, undone entries land on a redo stack that mcp_redo replays in order. The redo stack is cleared whenever a NEW mutation is performed (standard undo semantics), so redo only works until the next mutation. Pass count to redo multiple entries; pass preview=true to inspect without applying.

Roll back the most recent MCP mutation(s). Use this proactively — not just when the user asks — any time you want to recover from a mistake, clean up after a partial failure, or try a different approach. Specifically: call this if a tool call produced an error or unexpected result and you want a clean slate before retrying; if a multi-step sequence failed midway and you need to undo the steps that did succeed; or if get_errors shows new problems immediately after a mutation. Also use when the user says "undo", "revert", "go back", "restore", "that was wrong", "put it back", or similar. Prefer this over manually re-applying old values — it's exact (no guessing the prior state), atomic, and keeps the history clean. Only covers mutations made by MCP tools; does not cover changes the user made manually in the editor. Pass count to undo more than one entry in order; pass preview=true to see what would be undone without performing it (or call mcp_undo_history for a richer listing). After undo, scenes/scripts open in the editor are automatically reloaded.

List the undo and redo stacks: tool name, args summary, files affected, and age in seconds for each entry. Use to decide how far to undo (then call mcp_undo with the chosen count) or to confirm a specific change is still on the stack. Returns {undo: [...newest-first], redo: [...newest-first], cap: {entries, max_entries, bytes, max_bytes}}.

Measure the world-space distance between two Node3D nodes in a scene file. Returns both the full 3D delta and the horizontal XZ distance.

Modify a single property on a node in a .tscn scene file. For multiple properties at once use set_node_properties. ALWAYS use a tool to modify .tscn files — NEVER edit them as text. To attach or change a script, use attach_script (NOT modify_node_property with property="script") — modify_node_property only rewrites the .tscn on disk, leaving the editor's in-memory node without the script, which makes connect_signal fail.

Move a node to a different parent in a scene and optionally control its position among siblings.

Open a file in the Godot editor at a specific line (side-effect only).

Query a live node in the running scene tree. REQUIRES the game to be running with the MCPRuntime autoload connected. Returns class, path, valid, groups, and a map of property values. By default returns position, global_position, rotation, scale, visible, modulate — pass `properties:["..."]` to override. Set include_children=true to also list direct child nodes.