All servers / Gaming / Godot MCP server
Godot MCP server
MCP server for Godot game engine integration
Tested by ConnectATDScore 85 out of 100. Tested 2026-11-19 on package version 0.6.1. Package: godot-mcp-server · source
Score breakdown
| Runs | 18 / 20 | |
|---|---|---|
| Tool descriptions | 19 / 20 | |
| Package safety | 20 / 20 | |
| Maintenance | 20 / 20 | |
| Adoption | 8 / 20 |
What we saw
- Starts and answers the MCP handshake: yes (2.4 seconds including download)
- Tools offered: 71
- Last published: 2026-10-17
- Weekly downloads (npm): 832
- License: MIT · Direct dependencies: 3
Want this server set up for your team?
ConnectATD builds AI automation and wires up MCP servers like this one. Tell us what you are trying to do.
Talk to ConnectATDTools and how they are described
Agents choose tools from these descriptions. Under each name you can see how many of its parameters are explained.
get_godot_statusno parametersCheck if the Godot editor is connected to the MCP server. Also reports the plugin, server and Godot versions, and warns when the plugin and server versions differ.
get_guide1 of 1 parameter describedRead 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, setting resources and property values, troubleshooting "Runtime helper not connected", etc.).
list_dir2 of 2 parameters describedList files and folders under a Godot project path (e.g., res://). Returns arrays of files and folders in the specified directory.
read_file4 of 4 parameters describedRead a text file from the Godot project, optionally a specific line range. Useful for reading GDScript files, scene files, or any text-based content.
search_project4 of 4 parameters describedSearch the Godot project for a substring and return file hits with line numbers. Useful for finding usages of functions, variables, or any text pattern.
create_script2 of 2 parameters describedCreate 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.
create_scene5 of 5 parameters describedCreate a new Godot scene (.tscn) with a tree of nodes in one call, including their properties, textures, collision shapes, scripts and groups. Use this to create player scenes, UI screens, game objects, etc. **All-or-nothing:** the whole tree is built and checked in memory first. Unknown node types or property names (with suggestions), values of the wrong type, missing resource files and bad scripts are ALL reported together as path-pointed `validation_errors` (e.g. `nodes[1].children[0].properties.texture: no resource at res://hero.png`), and no file is written unless everything is valid.
read_scene2 of 2 parameters describedRead and parse a scene file to get its full node structure and properties. Use this to understand a scene before editing. NOTE: `include_properties: true` returns a hand-picked subset (position, rotation, scale, size, offset, visible, modulate, z_index, text, collision_layer, collision_mask, mass) optimized for quick scene overviews. To see ALL properties on a specific node — including @export'd script vars — use `get_scene_node_properties`.
get_scene_node_properties2 of 2 parameters describedReturn 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_node8 of 8 parameters describedAdd a node (optionally with a script, groups, properties and a whole tree of children) to an existing scene file in one call. Children format: {name|node_name, type|node_type, properties?, script?, groups?, children?}; unknown child keys are errors. **All-or-nothing:** the node tree is built and checked in memory before the scene is touched. Every problem (unknown types or properties with suggestions, wrong value types, missing resource files, bad scripts) is reported together in `validation_errors` with path-pointed prefixes, and nothing is saved unless everything is valid. Returns the new node's `node_path`.
remove_node2 of 2 parameters describedRemove a node from an existing scene file.
rename_node3 of 3 parameters describedRename a node in a scene.
move_node4 of 4 parameters describedMove a node to a different parent in a scene and optionally control its position among siblings.
attach_script3 of 3 parameters describedAttach or change a script on a node in a scene.
detach_script2 of 2 parameters describedRemove a script from a node in a scene.
instance_scene5 of 5 parameters describedAdd 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.
get_node_spatial_info3 of 3 parameters describedQuery 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.
measure_node_distance3 of 3 parameters describedMeasure the world-space distance between two Node3D nodes in a scene file. Returns both the full 3D delta and the horizontal XZ distance.
snap_node_to_grid5 of 5 parameters describedSnap a Node3D position to a grid in local or global space. Useful for modular level building and keeping 3D scenes aligned.
set_node_properties3 of 3 parameters describedSet one or more properties on a node in a .tscn scene. This is THE tool for changing node properties, including resources. ALWAYS use it (or create_scene/add_node) to change scenes; never edit .tscn files as text. Values are read according to each property's type: • numbers, bools, strings; enums by name ("Nearest", "TEXTURE_FILTER_NEAREST") or number • Vector2/3: {x, y[, z]} or [x, y[, z]]; Color: {r, g, b, a?} (0..1), "#ff8800" or "red"; Rect2: {x, y, width, height} • resources (texture, shape, mesh, material, stream, font, ...): a file path "res://icon.png", or an inline resource {"type": "RectangleShape2D", "size": {"x": 32, "y": 16}} whose other keys are its properties (nested resources work) • a property of a resource the node holds, via a colon path: {"shape:radius": 12, "material:albedo_color": "red"} • null clears a resource property **All-or-nothing:** every value is checked first and the scene is saved only if every write was accepted. Each write is read back: values Godot adjusted (clamped, wrapped) are listed in `adjusted`; a write Godot ignored is an error. Errors name the property and suggest close names. Scripts: use attach_script. Response: {ok, applied: [{property, old, new}], adjusted?}.
set_node_groups4 of 4 parameters describedSet, add, or remove a node's group memberships in a .tscn scene file. Groups persist to disk so the running game can call get_tree().get_nodes_in_group(name).
get_node_groups0 of 2 parameters describedRead the list of groups a node belongs to in a .tscn scene file.
find_nodes5 of 5 parameters describedSearch 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.
save_resource_to_file2 of 4 parameters describedSave a Resource currently held by a node (or sub-resource) to a standalone .tres file so it can be referenced by other scenes / shared / committed. The node's property is then re-pointed to the saved file. To change the file later, call set_node_properties with scene_path set to the .tres (this affects every scene that uses it). Works for any Resource subclass: Material, Mesh, Shape, Curve, Gradient, etc.
get_resource_info4 of 4 parameters describedInspect 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.
list_signal_connections5 of 5 parameters describedList 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).
connect_signal5 of 6 parameters describedConnect 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, otherwise the editor's in-memory node will not see the script and this tool will reject the connection.
disconnect_signal2 of 5 parameters describedRemove a signal connection from a .tscn scene file. No-op if the connection doesn't exist.
call_method7 of 7 parameters describedInvoke 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** — positional arguments, read according to the method's parameter types (same value forms as set_node_properties): a Texture2D parameter takes `"res://icon.png"`, a Vector2 takes `{x, y}`, a Color takes `"red"`. For `set(property, value)` the value is read by that property's type. Wrong types are errors, not silent no-ops. Untyped (Variant) parameters take plain JSON; use `{type:"Resource", path}` or `{type:"Vector2", x, y}` to pass typed values there. **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?}`.
edit_script5 of 5 parameters describedEdit an existing GDScript (.gd) file in place by replacing old_text with new_text, and save. The text can be any size — a single line, a function, or the whole file for a full rewrite. If old_text 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.
validate_script1 of 1 parameter describedValidate a GDScript file for syntax errors using Godot's built-in parser. Good for ordinary project scripts after editing. For @tool/editor-plugin addon scripts this isolated parser path may return valid:false with diagnostics_available:false because dependencies and editor context are not fully loaded; in that case, use get_errors/get_console_log after enabling or reloading the addon for actionable details.
create_folder1 of 1 parameter describedCreate a directory (with parent directories if needed).
delete_file4 of 4 parameters describedPermanently 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.
delete_folder6 of 6 parameters describedRecursively 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.
write_file5 of 5 parameters describedWrite UTF-8 text content to any file in the project. Creates the file if missing; REFUSES to clobber an existing file unless overwrite=true. Parent directories are auto-created (override with create_dirs=false). Refuses to write to plugin source (anywhere under res://addons/godot_mcp/ except res://addons/godot_mcp/cache/) unless force=true. Refuses paths containing ".." or "." traversal segments (would escape the project tree). Use this for non-GDScript text: .gdignore, .gitignore, README.md, .json configs, .gdshader files, custom .tres data, fixture files for tests, any plain-text content. For GDScript with boilerplate (class_name / extends), prefer create_script which adds those automatically and validates the path is .gd. The write is captured by the undo system: a single mcp_undo restores the prior content (when overwriting) or deletes the file (when creating new). Binary content is NOT supported — for binary files write a GDScript helper that produces the file and run it via run_scene, or copy/move via rename_file. Editor sync after write: the call replaces the ResourceLoader cache entry for .tscn/.tres/.gdshader/.scn so the next load() sees the new content (sets cache_evicted:true on success), force-reloads any Script resource for .gd writes (sets script_reloaded:true), and reloads an open scene tab whose .tscn was just written (sets scene_reloaded:true). The refresh runs unconditionally for the recognized extensions — flags reflect whether each step succeeded, not whether a stale cache happened to exist beforehand, because Godot keeps resources alive in places ResourceLoader.has_cached() cannot see (open tabs, EditorFileSystem index). The script editor's in-memory tab buffer is NOT swapped (Godot exposes no public API for that) — if you wrote to a .gd that is currently open in the editor, the user may need to refocus the tab to see the new source. When any refresh action ran successfully, an editor_refresh:{cache_evicted, scene_reloaded, script_reloaded} field is included in the response. Returns {ok, path, existed, bytes_written, message} (plus editor_refresh when applicable).
rename_file3 of 3 parameters describedRename or move a project file. By default also rewrites every literal reference to the old path in other text-format project files (.tscn, .tres, .gd, .cs, .gdshader, project.godot) and updates any matching `autoload/*` entry in ProjectSettings, so scenes and preloads keep working. When Godot exposes a reliable scene-dirty API, clean open scene tabs that referenced the renamed file are reloaded (close + reopen), while dirty tabs are preserved and returned in scenes_skipped_dirty. On Godot versions without that API, open scene reload is skipped with scene_reload_warnings to avoid discarding unsaved changes; the files are still correct on disk, but the user may need to manually reopen the tab to clear stale editor paths. Pass update_references:false to skip both reference rewrite and reload. Returns references_updated:[{file, replacements}], scenes_reloaded:[paths], and optionally scenes_skipped_dirty or scene_reload_warnings.
list_scriptsno parametersList all GDScript files in the project with basic metadata.
get_project_settings2 of 2 parameters describedConcise project settings summary: main_scene, window size/stretch, physics tick rate, and render basics.
get_input_map1 of 1 parameter describedReturn 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.
get_collision_layersno parametersReturn named 2D/3D physics collision layers from ProjectSettings.
get_node_properties1 of 1 parameter describedGet 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).
get_console_log2 of 2 parameters describedReturn 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.
get_errors3 of 3 parameters describedGet 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.
clear_console_logno parametersMark the current position in the Godot editor log. Subsequent get_console_log and get_errors calls will only return output after this point.
open_in_godot2 of 2 parameters describedOpen a file in the Godot editor at a specific line (side-effect only).
scene_tree_dump4 of 4 parameters describedDump the scene tree of the scene currently open in the Godot editor (node names, types, and attached scripts) as an indented text block. Reflects unsaved edits (uses the live editor tree, not the .tscn on disk). All args are optional; with no args the entire tree is returned (existing behavior). Opt-in scoping / pagination (use these on large scenes to keep responses small): • subtree_root — start at a node path relative to the scene root (e.g. "UI/HUD"). Empty or "." means the scene root. Depth resets to 0 at this node. • max_depth — stop traversal at depth N from the (subtree_)root. 0 = only the root itself. Omit or pass a negative value for unlimited. • offset / limit — paginate by flat DFS preorder index. offset skips the first N nodes; limit caps how many are emitted. Response fields: • tree — the indented text (only nodes inside the window are rendered). • scene_path — the editor scene file. • total_node_count — total nodes inside the (subtree_root + max_depth) scope. Always returned. • truncated — true ONLY when offset/limit clipped output. max_depth is intentional scoping, not truncation. • next_offset — set to offset + emitted when truncated; call again with this offset to continue. • subtree_root — echoed when you passed one.
get_editor_selectionno parametersReturn 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 `set_node_properties`, `attach_script`, `remove_node`, etc. See the `selection-workflow` guide for end-to-end patterns.
set_editor_selection2 of 2 parameters describedReplace or extend the editor's Scene-dock selection. Two main uses: (1) after `add_node`, focus the user's gizmo on the freshly-created node so they can see/manipulate it immediately, and (2) draw the user's attention to a node the AI just modified or discovered ("here is the offending node — selected for you in the Scene dock"). Pre-validates every path against the live edited scene tree before mutating — if any path is unresolved, no selection change happens and `not_found` is returned. Args: `node_paths` (string OR array of strings; scene-relative, "." = scene root, "UI/HUD/Label" for nested), `mode` ("replace" default = clear existing then select; "add" = append to existing). Returns `{ok, scene_path, selected:[{path,name,type}], not_found:[], mode, count}`. Use `get_editor_selection` afterwards (or `scene_tree_dump`) to verify.
close_editor_tabs2 of 2 parameters describedClose 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.
list_settings1 of 1 parameter describedBrowse 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.
update_project_settings1 of 1 parameter describedUpdate one or more Godot project settings. Pass a dictionary of setting paths to their new values. Use list_settings first to discover available setting paths, current values, and valid options for a category. For input action bindings, prefer configure_input_map — if you do pass input/* keys here, partial updates are merged safely (existing events are preserved).
configure_input_map4 of 4 parameters describedAdd, remove, or replace input actions and their key/button bindings. Use get_input_map to see current actions before modifying.
run_scene5 of 5 parameters describedLaunch a scene in the Godot editor. By default the call BLOCKS until the editor flips to playing state (so the next get_errors / take_screenshot / send_input call sees a real game). The response includes started, runtime_connected, wait_for_started_ms, wait_for_runtime_ms, scene_path, and runtime_root. Use runtime_root (e.g. "/root/Main") as the prefix for query_runtime_node node_path arguments — it is computed from the actual root node name in the .tscn, NOT from the file name. Set wait_for_runtime=true to additionally wait for the in-game MCPRuntime helper to connect (required before take_screenshot / send_input will work). By default this watermarks the log surfaces so the subsequent get_console_log / get_errors only show THIS run's output — no more mistaking stale errors from a previous run for fresh ones (set clear_output:false to keep reading the full history). Recommended testing loop: run_scene({wait_for_runtime:true}) → query_runtime_node / send_input / take_screenshot → get_errors → stop_scene.
stop_sceneno parametersStop the currently running scene in the Godot editor. Always stop the scene before editing code to avoid errors repeating every frame.
is_playingno parametersCompatibility shim: returns {playing, scene}. For richer info (uptime, runtime helper connectivity, last-launched target) prefer get_runtime_status.
get_runtime_statusno parametersCombined 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.
wait2 of 2 parameters describedSleep server-side. Useful between input events to let the game process them. Capped at 30000ms / 30s. Pass either ms or seconds (ms wins if both given).
take_screenshot2 of 2 parameters describedCapture the current viewport of the running game and save it as a PNG. REQUIRES the game to be running with the MCPRuntime autoload connected (run_scene with wait_for_runtime=true first). Returns resource_path, absolute_path, width, height, and (optionally) base64_png. Default save location is res://addons/godot_mcp/cache/screenshots/.
send_input1 of 1 parameter describedSynthesize an InputEvent and dispatch it to the running game via Input.parse_input_event. REQUIRES the game to be running with the MCPRuntime autoload connected. Use this to drive automated tests: click buttons, press keys, fire input actions. For multi-step interactions, alternate send_input → wait → query_runtime_node / take_screenshot. Unknown key names, unknown actions and unknown event fields are errors (they used to be ignored), so a returned ok means the event really fired.
query_runtime_node4 of 4 parameters describedRead a live node in the running game. REQUIRES the game to be running with the MCPRuntime autoload connected. Returns class, path, script, groups and property values. By default (no `properties`) it returns everything that describes the node's current state: all script variables (health, score, ...) plus every stored property that differs from the class default (a Label's text, a body's velocity, ...), plus global_position for 2D/3D/UI nodes. Pass `properties: ["text", "material:albedo_color"]` to read specific ones (colon paths read into resources); unknown names are errors with suggestions. Large arrays and strings are truncated. Set include_children=true to list direct children.
get_performance_monitorsno parametersSnapshot 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.
get_runtime_log2 of 2 parameters describedReturn 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.
classdb_query3 of 3 parameters describedQuery 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.
rescan_filesystemno parametersTrigger a full filesystem rescan in the Godot editor. Use after creating, deleting, or modifying files externally (e.g. from the terminal or another tool). The scan is asynchronous and returns immediately. If a scan is already in progress (often happens right after a batch of mutations), the call returns ok:true with already_scanning:true — the in-flight scan will pick up your recent disk changes, no new scan is triggered. Response: {ok, already_scanning, message}.
setup_autoload3 of 3 parameters describedRegister, unregister, or list autoload singletons. Autoloads are scripts/scenes loaded automatically at project start.
generate_2d_asset6 of 6 parameters describedRender 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.
map_project2 of 2 parameters describedCrawl 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.
mcp_undo2 of 2 parameters describedRoll 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.
mcp_redo2 of 2 parameters describedRe-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.
mcp_undo_history1 of 1 parameter describedList 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}}.
batch_execute3 of 3 parameters describedRun 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).
Tested in a sandbox with an empty environment: no API keys, a throwaway folder, nothing from a real account. A passing test shows the server runs and responds. It is not a security audit.