godot-mcp

Read a text file from the Godot project, optionally a specific line range. Useful for reading GDScript files, scene files, or any text-based content.

Read 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`.

Remove a node from an existing scene file.

Rename 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.

Rename a node in a scene.

Trigger 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}.

Launch 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.

Save 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 loaded-from-disk version, so future set_resource_property calls write through to that file. Works for any Resource subclass: Material, Mesh, Shape, Curve, Gradient, etc.

Dump 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.

Search the Godot project for a substring and return file hits with line numbers. Useful for finding usages of functions, variables, or any text pattern.

Synthesize 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.

Create and assign a collision shape resource to a CollisionShape2D or CollisionShape3D node. Supports: CircleShape2D, RectangleShape2D, CapsuleShape2D, SphereShape3D, BoxShape3D, etc.

Replace 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.

Create and assign a material to a MeshInstance3D, CSG, or GeometryInstance3D node. Supports StandardMaterial3D or loading from file.

Create and assign a mesh resource to a MeshInstance3D node. REQUIRED to make 3D geometry visible. Primitive types: BoxMesh, SphereMesh, CylinderMesh, CapsuleMesh, PlaneMesh, PrismMesh, TorusMesh, QuadMesh, TextMesh. Or load from file.

Set, 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).

Set MULTIPLE properties on a node in a single tool call. **Atomic pre-validation** — every entry is checked (name exists on the node's class plus its attached script's @export'd properties; Resource-typed properties must use the dedicated resource tools) BEFORE anything is written. If ANY entry fails, the response is `ok: false` with a `validation_errors` array (e.g. `properties.color: property does not exist on Sprite2D`) and ZERO mutation occurs — no scene save, no half-applied state. On success, returns the `applied` list with old/new values per property. Resource-typed properties must use set_resource_property / set_sprite_texture / set_mesh / set_material / set_collision_shape.

Modify a property on a Resource that is currently held by a node (or by another resource attached to that node). Use this to tweak shape radii, material colors, gradient stops, etc., WITHOUT recreating the resource. resource_path walks from the node down to the resource using "/"-separated property names, e.g. "shape", "material", or "material/next_pass". After the change, saves the scene.

Assign a texture resource to a Sprite2D / Sprite3D / TextureRect node in a .tscn scene file. Modes: • FromPath — load any texture file from disk (png/jpg/webp/svg/.tres) via load(). Returns whatever Texture2D the importer produced (usually CompressedTexture2D). Most common after generate_2d_asset. • ImageTexture (DEPRECATED ALIAS for FromPath, kept for back-compat) • NewImageTexture — force-create an ImageTexture (in-memory) from a raw image file. • PlaceholderTexture2D — in-scene placeholder of a given size. • GradientTexture2D / NoiseTexture2D — procedural textures. Response always includes texture_class (the actual Godot class the texture decoded to), width, height, and texture_path so the agent can confirm what landed without an extra get_resource_info call.

Register, unregister, or list autoload singletons. Autoloads are scripts/scenes loaded automatically at project start.

Snap a Node3D position to a grid in local or global space. Useful for modular level building and keeping 3D scenes aligned.

Stop the currently running scene in the Godot editor. Always stop the scene before editing code to avoid errors repeating every frame.

Capture 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/.

Update 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).

Validate 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.

Sleep 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).

Write 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).