Godot MCP server

Read from the package source without running it. The installed server may list more.

• add_node

  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 (

• attach_script

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

• batch_executewrite action

  Run an ordered list of MCP tool calls as a single composite operation.

• classdb_query

  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.

• clear_console_log

  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_editor_tabs

  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

• configure_input_map

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

• connect_signal

  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

• create_folderwrite action

  Create a directory (with parent directories if needed).

• create_scenewrite action

  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 t

• create_scriptwrite action

  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 i

• delete_filewrite action

  Permanently delete a file from the project. REQUIRES confirm=true as an explicit safety gate \u2014 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 \u2014

• delete_folderwrite action

  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 REFUS

• detach_scriptwrite action

  Remove a script from a node in a scene.

• disconnect_signalwrite action

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

• edit_script

  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 f

• find_nodes

  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: \u2022 name_pattern: case-insensitive. If it contains "*" or "?" it is treated as a glob (matchn); otherwi

• generate_2d_asset

  Render an SVG to a PNG asset on disk via Image.load_svg_from_buffer. The SVG is rendered directly from bytes \u2014 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.

• get_collision_layers

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

• get_console_log

  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

• get_editor_selection

  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

• get_errors

  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 bef

• get_godot_status

  Check if Godot editor is connected to the MCP server.

• get_guide

  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: …. Call with {slug: "..."} to get the full markdown. Useful when a workflow is non-obvious (testing a running game, choosing between scene-editing tool

• get_input_map

  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.

• get_node_groups

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

• get_node_properties

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

• get_node_spatial_info

  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.

• get_performance_monitors

  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

• get_project_settings

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

• get_resource_info

  Inspect ANY Godot Resource. Two modes: \u2022 path mode: pass {path: "res://foo.png"} for a resource on disk (.tres / .res / image / .glb / .ogg / .tscn / etc.) \u2022 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 A

• get_runtime_log

  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 \u2014 runtime errors do NOT appear in get_console_log). Returns ent

• get_runtime_status

  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`, `patc

• get_scene_node_properties

  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 curren

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

• is_playing

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

• list_dir

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

• list_scripts

  List all GDScript files in the project with basic metadata.

• list_settings

  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,

• list_signal_connections

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

• map_project

  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.

• mcp_redo

  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.

• mcp_undo

  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.

• mcp_undo_history

  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.

• measure_node_distance

  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_node_property

  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 \u2014 NEVER edit them as text. To attach or change a script, use attach_script (NOT modify_node_property with property="script") \u2014 modify_node_property only rewrites the .tscn on disk, leaving the editor's in-memory node without the script

• move_node

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

• open_in_godot

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

• query_runtime_node

  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 \u2014 pass `properties:["..."]` to override. Set include_children=true to also list direct child nodes.

• read_file

  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_scene

  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 s

• remove_nodewrite action

  Remove a node from an existing scene file.

• rename_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 (c

• rename_node

  Rename a node in a scene.

• rescan_filesystem

  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,

• run_scenewrite action

  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 \u

• save_resource_to_file

  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.

• scene_tree_dump

  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

• search_project

  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.

• send_inputwrite action

  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 \u2192 wait \u2192 query_runtime_node / take_screenshot.

• set_collision_shapewrite action

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

• set_editor_selection

  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 m

• set_materialwrite action

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

• set_meshwrite action

  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_node_groups

  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_node_properties

  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 do

• set_resource_property

  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.

• set_sprite_texture

  Assign a texture resource to a Sprite2D / Sprite3D / TextureRect node in a .tscn scene file. Modes: \u2022 FromPath \u2014 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. \u2022 ImageTexture (DEPRECATED ALIAS for FromPath, kept for back-compat) \u2022 NewImageTe

• setup_autoload

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

• snap_node_to_grid

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

• stop_scene

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

• take_screenshot

  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_project_settingswrite action

  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_script

  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 actionab

• wait

  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_filewrite action

  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 (

• Code scan33 source files scanned13/25
• –Live reliabilityno gateway calls yet and no remote to proben/a
• –Tool poisoningtools not inspected (local package is not executed); not countedn/a
• Auth qualitylocal package, no credentials required12/15
• Maintenancelast push 28 days ago15/15
• Maintainer identityregistry namespace matches repository owner; GitHub account older than a year8/10

Godot: common questions

Is Godot MCP server safe?

Mostly: it is graded B (74/100). Read the Godot safety report

How do I install Godot?

It runs on your machine. Copy the Claude Code, Claude Desktop or Cursor config from the install section.

Does Godot need an API key?

Not as far as the registry entry and our scan can tell: no credentials are declared or required.

Is Godot maintained?

The last commit was 28 days ago (2026-08-24). The latest release is v0.6.0.

What can I use instead of Godot?

Servers from other publishers that do the same job: Unreal Engine MCP server.