io.github.TomasLucasUTN/godot-mcp-bridge

Add a node to an existing scene file, optionally with a script, groups, and a whole sub-tree of children in the same call. Children take the same keys as add_node itself ({name|node_name, type|node_type, properties?, script?, groups?, children?}); an unknown key is an error.

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

Run a sequence of {tool, args} calls in ONE request instead of N round-trips — the way to build several scenes at once (batch_scene_edit covers only one). Dispatches inside the EDITOR, so it cannot reach tools that live in the running game (take_screenshot, send_input, query_runtime_node, game_eval, ...); call those directly. NOT a transaction: each scene tool still does its own load/save. stop_on_error halts at the first failure. Cannot be nested.

Apply many structural/property edits to ONE scene with a single load and a single save — much faster than N separate add_node/set_node_properties/... calls on a closed scene (each of those re-loads and re-saves the whole .tscn). For an open scene the whole batch lands on the live editor tree and marks it dirty (no disk write). Ops run in order; stop_on_error (default true) discards the entire batch — nothing saved — on the first failure. Op types: add_node {node_name,node_type,parent_path,properties?,script?,groups?,children?}, set_properties {node_path,properties}, remove_node {node_path}, rename_node {node_path,new_name}, move_node {node_path,new_parent_path,sibling_index?}.

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.

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 new Godot scene (.tscn) file with nodes. Use this to create player scenes, UI screens, game objects, etc.

Create a NEW GDScript file (.gd) that does not exist yet. Use this for creating new scripts, NOT for editing existing files (use edit_script for edits). Use classdb_query to verify unfamiliar Godot class methods. After creating a script, consider using run_scene to test and get_errors to check for issues.

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.

Diagnose why the Godot editor is (or is not) connected — the #1 setup frustration. Works even when nothing is connected (runs entirely in the MCP server). Returns a pass/fail checklist plus, when disconnected, an ordered list of concrete remedies (enable the plugin, wrong port, Godot version, the _console.exe stub, etc.). Call this first when tools report "Godot editor is not connected".

Disable a toolset so its tools stop appearing in list_tools. Does not affect tool names already known to the client.

Duplicate a node and its children within the same scene, inserted right after the original as a sibling.

Apply a SMALL, SURGICAL code edit (1-10 lines) to GDScript files. Auto-applies changes. For large changes, call multiple times. ONLY for .gd files - NEVER for .tscn scene files. Use classdb_query to verify unfamiliar Godot class methods. After making changes, consider using run_scene to test and get_errors to check for issues.

Enable an optional toolset so its tools appear in the next list_tools call. "core" (look around, edit scenes/scripts, run the game, read errors) is always on; the rest are opt-in to keep the surface small. Use find_tools or list_toolsets to find which one holds the tool you want.

Recursively find all nodes of a given class (or subclass, unless exact_match) in a scene. Returns node_path/node_name/node_type for each match.

Find a tool by what you want to do, across all 231 — including the ones whose toolset is off. Ask "autotile a tilemap" or "record input" and get the matching names, a one-line summary each, and the toolset to enable. Use this when you know what you want to DO but not what it is called; list_toolsets is for browsing.

Return the latest lines from the Godot editor output log (as a single "content" string). Pass filter to keep only lines containing a substring — cheaper than pulling the whole log to find one message.

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. 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 — the same content as the MCP resources, exposed as a tool for clients that do not support them. Call with no args to list them, or with a slug for the full markdown. Worth reading when a workflow is non-obvious: testing a running game, choosing between the scene-editing tools, "Runtime helper not connected".

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

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 full engine stdout (script prints, errors, warnings) use get_console_log — the editor already captures the running game's stdout. Returns entries with ts_ms, level, and text plus started_at_ms (when the helper started) and now_ms.

List a scene's resource dependencies (instanced sub-scenes, scripts, external resources) via ResourceLoader.get_dependencies — reads the file's dependency table directly, no need to load the scene.

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.

List every toolset with what it is for, how many tools it holds, and whether it is enabled. Only "core" is on by default; if the tool you need is not in list_tools, find its toolset here and enable that one.

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

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 node structure (and optionally properties). Use this to understand a scene before editing. On large scenes pass max_depth for a cheap shallow read — a depth-limited node reports children_truncated instead of expanding.

Remove a node from an existing scene file.

Rename a node in a scene.

Render a 2D scene to a PNG WITHOUT running the game — the cheap way to actually look at a scene. take_screenshot needs a live game (launch, runtime connection, remembering to stop it); this renders offscreen in the editor, auto-framing the scene's content, and leaves no editor state changed. Use it to check layout, sprite placement, and whether a level looks like you think it does. 2D only.

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. NOT enough for a new autoload or a new class_name — those need restart_editor.

Restart the Godot editor. Needed for two things a rescan cannot fix: an AUTOLOAD added this session, and a brand-new class_name. Until the editor restarts, every script referencing them fails to compile — and a node whose script failed to compile loses its exported properties, so create_scene/add_node write defaults and still report ok. Symptom: you set a property, the call succeeds, and the value is wrong when you read it back. The bridge disconnects with the editor; poll get_godot_status until it reconnects (usually 20-40s).

Launch a scene in the Godot editor. Blocks until the editor is playing, so the next get_errors / take_screenshot call sees a real game. Use the returned runtime_root (e.g. "/root/Main") as the prefix for query_runtime_node paths — it comes from the root node name in the .tscn, NOT the file name. wait_for_runtime=true also waits for the in-game MCPRuntime helper, which take_screenshot and send_input need. Full loop: get_guide("testing-loop").

Dump the scene tree of the scene currently open in the Godot editor (node names, types, and attached scripts). Pass max_depth to keep the output small on large scenes — a depth-limited branch reports its descendant count instead of expanding. Start shallow (max_depth 1-2) for an overview, then drill in.

Search the Godot project for a substring and return file hits with line numbers. At most max_results matches (default 50), each line cut at 200 chars, because the answer costs context. When it stops early it says `truncated: true` and reports `returned` rather than a total it never finished counting.

Set properties on ONE node — one or many, in a single call and a single save. For the same property across many nodes use batch_set_property. Non-atomic: each property is applied independently and the response separates "applied" from "failed", so partial success is visible. Never edit a .tscn as text. To set a script use attach_script, NOT a "script" property here: that only rewrites the file, leaving the editor's in-memory node scriptless, which makes connect_signal fail. Resource-typed properties need set_resource_property / set_sprite_texture / etc.

Point an exported property at another NODE in the same scene — the wiring you would otherwise do by dragging a node into an inspector slot. Use for any @export typed as a node (`@export var target: Area2D`, `@export var health: HealthComponent`) or as a NodePath. set_node_properties CANNOT do this: it takes a JSON value, and this needs a live object reference. Fails loudly if the property does not exist or is typed for a different node class, instead of silently doing nothing.

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

Validate many GDScript files at once. Pass "paths" (array of res:// .gd paths) to check a specific set, or omit it to sweep the project (addons/ excluded unless include_addons). Returns only the invalid scripts, each with a message you can act on, plus elapsed_ms. PREFER an explicit paths list: validation runs on the editor's main thread at roughly 34ms per script, so a whole-project sweep on a large codebase is slow and can approach the bridge's 20s watchdog.