io.github.tomyud1/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.

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

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.

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.

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.

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.

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.

Find every node in a .tscn that belongs to a given group. Returns paths, names, and types. Useful for verifying that level.gd will actually pick up the right nodes via get_tree().get_nodes_in_group().

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

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

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

Combined editor + runtime status snapshot. Returns playing, playing_scene, last_launched ("current"|"main"|res-path), uptime_ms since the most recent run_scene, and runtime_helper_connected (true once the in-game MCPRuntime autoload is talking to the MCP server).

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.

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.

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.

Remove a node from an existing scene file.

Rename or move a file, optionally updating references in other files.

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.

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

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.