Godot AI
Godot AI is an MCP server that connects AI clients to a live Godot editor for authenticated, multi-session scene, script, resource, runtime, and project automation.
Manage editor sessions: list connected editors, activate a session by ID or name/path hint, inspect editor state, screenshots, logs, performance monitors, selection, and reload the plugin.
Author scenes and nodes: open/save/create scenes, read hierarchy, create/find/delete/duplicate/rename/reparent nodes, set properties, manage groups, and batch multi-step edits atomically.
Work with scripts: create, patch, attach, detach, read, and outline GDScript; C# files are text-only with no .NET build/compiler diagnostics.
Build resources and visuals: search/load/assign/create resources, materials, raw shaders, VisualShader graphs, themes, UI layouts, vector draw recipes, animation clips/tracks/presets, particles, cameras, and audio players.
Author 2D/3D level content: TileMap/TileMapLayer cells, TileSet atlas inspection, GridMap cells/library items, CSG shapes, and bounded navigation baking/path queries.
Configure projects: run/stop the game, get/set project settings, set main scene, autoloads, and input actions/bindings (keyboard, mouse, gamepad).
Inspect and control running games: scene tree, node info, UI elements, suspend/resume/next frame, keyboard/mouse/gamepad/action input, and frame-timed input sequences.
Run and inspect GDScript test suites and batch editor sub-commands with rollback-on-failure.
Configure supported MCP clients, list/invoke third-party custom tools, and query Godot ClassDB API metadata.
Security-oriented features include authenticated local connections, loopback-only editor WebSocket, signed releases, project-confined writes, and protected project files.
Allows AI assistants like Codex to access and manipulate a live Godot editor environment.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Godot AI Create a Camera3D named MainCamera under /Main."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Godot AI
Godot AI connects Claude Code, Codex, Cursor, and other MCP clients to a live Godot editor. Its 46 tools and 120+ operations build scenes, edit nodes and scripts, wire signals, and configure UI, materials, animation, particles, cameras, and environments.
21,000+ monthly active installs · 30M+ tool calls in the last three months · 3,200+ GitHub stars Install and tool-call counts come from anonymous telemetry and exclude opted-out installs: the 30 days, and July 27 onward, to October 25, 2026.
Quick start
You need Godot 4.7+, uv (it runs the Python server), and an MCP client.
Install uv (once):
macOS/Linux:
curl -LsSf https://astral.sh/uv/install.sh | shWindows (PowerShell):
irm https://astral.sh/uv/install.ps1 | iex
Install the add-on from the Asset Store (Godot's AssetLib tab), or from a GitHub release into
your-project/addons/godot_ai/.Enable it: Project → Project Settings → Plugins → Godot AI.
Connect your client: in the Godot AI dock, press Configure next to your client, or Configure all. Restart the client if it doesn't notice the change.
Already installed? Click Update in the dock. Never extract a new
version over an existing addons/godot_ai/. From v3, the same button migrates
you to v4 (migration guide).
The dock configures 26 clients, including Claude Code, Claude Desktop, Codex, Cursor, VS Code, Antigravity, Gemini CLI, and Hermes Agent, and shows a Run this manually command for the rest.
Use the dock-generated command: it pins the matching version, ports, and tool domains. v4 clients connect through
godot-ai attachover stdio; a barehttp://127.0.0.1:8000/mcpentry cannot authenticate.Updates repin owned client entries automatically. The default scope is global, so this also redirects other projects still on an older version; update them too. Reconfigure after changing ports, telemetry preferences, or tool domains.
Pi Coding Agent needs an MCP extension that reads
~/.pi/agent/mcp.json. Cherry Studio is not supported in v4; remove stale v3 entries in Cherry Studio itself.
Details: client configuration.
CLI-configured clients default to global user scope. Set Editor Settings →
Plugins → godot_ai/mcp_client_scope to project (or local, where supported),
then press Configure again.
Configure removes existing godot-ai entries from every scope before
writing the selected one. This can modify a checked-in .mcp.json, but does not
touch other server entries. Remove affects only the selected scope.
Launch Godot from the project directory so the client CLI writes configuration
in the right place. Claude Code also requires one-time approval from claude
run inside that project.
GDScript is fully supported: scripts are parse-validated, hot-reloaded,
attached, and outlined. C# is text-only: script_create / script_patch
write .cs files and script_manage(op="find_symbols") outlines them, but
Godot AI does not build .NET or report compiler errors. Attaching a .cs needs
a .NET-enabled editor build. C# support.
Try it
"Show me the current scene hierarchy."
"Create a Camera3D named MainCamera under /Main."
"Run the scene test suite."
"Build a voxel block-world game with a player, blocks to place and destroy, and save slots."
Related MCP server: godot-ai-mcp
Security
Godot AI has prioritized security from the start. Today that includes:
Signed releases. The in-editor updater verifies the signature and every file before it installs anything.
Authenticated local connections. The server and the editor accept only connections that present rotating credentials, and the editor connection is loopback-only.
Project confinement. Writes stay inside your project, and
project.godot,override.cfg, and.godot/are off-limits.A guarded release pipeline. Pinned dependencies, qualification on Linux, macOS, and Windows, and a human approval before anything is published.
Open disclosure. Vulnerabilities are fixed and published as security advisories.
Update promptly. 4.3.1, for example, removes the emSign root certificates compromised in October 2026.
That said, attacks on open-source supply chains are increasing, and more critical vulnerabilities will appear in Godot AI, its dependencies, and the tools around it. Following advisories and the wider security landscape is your responsibility. Godot AI is MIT-licensed open source, provided as is; you use it at your own risk.
MCP client
→ godot-ai attach (stdio)
→ Python server (authenticated HTTP, port 8000)
→ Godot editor plugin (authenticated WebSocket, port 9500)Both local hops use independent rotating capabilities; neither falls back to unauthenticated access, and the editor WebSocket stays loopback-only. These controls do not protect against a compromised same-user process, and Windows does not claim isolation from other local accounts. See the security model, package trust boundaries, and agents on another machine or in a container.
Privacy
Anonymous telemetry records an installation UUID, event, outcome, duration,
platform, and version, never code, scene contents, or project or file names.
Opt out with GODOT_AI_DISABLE_TELEMETRY=true or DISABLE_TELEMETRY=true, or
in the editor. Details.
Docs and help
Tools, operations, and resources · Write and run tests for your game · Community addons and custom tools
Upgrading from v3 · Linux troubleshooting (Bazzite, Steam, Flatpak) · Changelog
Contributing · Discord for questions and showcases · GitHub Issues for bugs
Star History
License: MIT
Available Tools
47 toolsanimation_createAnimation CreateA
Create a new Animation clip inside an AnimationPlayer's default library.
After creating the clip, add tracks via animation_manage ops
add_property_track / add_method_track / create_simple.
Track node paths are stored relative to the AnimationPlayer's
root_node (default: its parent), not to the scene root — see
animation_manage preset ops for a forgiving target_path that
accepts either form.
If player_path doesn't resolve, an AnimationPlayer is auto-created
at that path (parent must exist).
Inputs: name (required), length (required), player_path (required), loop_mode, +2 more. Returns: object
animation_manageAnimation ManageA
Animation authoring (players, libraries, tracks and AnimationTree graphs).
Ops: • tree_create(parent_path, player_path, name="AnimationTree", root_type="state_machine") Create an inactive AnimationTree linked to the player. root_type: state_machine|blend_tree|blend_space_1d|blend_space_2d. • tree_get(tree_path, graph_path="") Read graph nodes/points, properties, edges, triangles and tree parameters. • tree_node_add(tree_path, name, node_type="AnimationNodeAnimation", properties=None, position=None, graph_path="") Add a native node. position: {x,y}. State machines accept AnimationRootNodes. • tree_node_remove(tree_path, name, graph_path="") Remove a node and its edges. Undo restores identities, edges and parameters. • tree_node_set(tree_path, properties, graph_path="") Set editable properties of the selected graph node, e.g. animation or fadein_time. Configure variable input counts (0 to 256) at creation. This op preserves existing input topology. • tree_connect(tree_path, input_node, input_index, output_node, graph_path="") Connect a blend-tree input port. Occupied ports/outputs and cycles are refused. • tree_disconnect(tree_path, input_node, input_index, graph_path="") Disconnect a blend-tree input port. • tree_point_add(tree_path, name, position, node_type="AnimationNodeAnimation", properties=None, at_index=-1, graph_path="") Add a named blend-space point (native limit: 64). Names cannot contain '.' or '/'. position: number for 1D, {x,y} for 2D. at_index=-1 appends. • tree_point_set(tree_path, name, position, graph_path="") Move a blend-space point. Use tree_node_set at graph_path="Space/Point" for its properties. • tree_point_remove(tree_path, name, graph_path="") Remove a point. Undo restores its resource, name, index and manual triangles. • tree_transition_add(tree_path, from_state, to_state, graph_path="", properties=None) • tree_transition_set(tree_path, from_state, to_state, graph_path="", properties=None) • tree_transition_remove(tree_path, from_state, to_state, graph_path="") State-machine transitions. Properties include xfade_time, switch_mode, advance_mode, advance_condition and advance_expression. Start/End follow native restrictions.
Blend-space node properties include min_space, max_space, snap, labels, blend_mode, sync_mode and cyclic_length. 2D triangulation is automatic; a subsequent tree_get reads generated triangles after the editor updates them. Graph paths select nested resource names, e.g. "Locomotion/Blend"; empty selects tree_root. Graph writes are undoable and preserve shared resource identity. Enable a completed tree or set parameters with node_set_property (e.g. property="parameters/Blend/blend_amount").
• player_create(parent_path, name="AnimationPlayer") Create an AnimationPlayer with empty default library. • library_add(player_path, resource_path, library_name="") Attach a saved AnimationLibrary to an AnimationPlayer or AnimationTree. Undoable. Empty library_name selects the default library. Existing names/resources are refused. • library_remove(player_path, library_name="") Detach a library; clears autoplay if it points into that library. Undoable. • library_list(player_path) List library names, resource paths and clip names. Includes autoplay for AnimationPlayer. • delete(player_path, animation_name) Delete an animation clip from the default library. Undoable. • validate(player_path, animation_name) Check all track paths resolve. Returns broken_count + per-track issues. • add_property_track(player_path, animation_name, track_path, keyframes, interpolation="linear") Add a property track. track_path: "NodeName:property". keyframes: [{time, value, transition?}, ...]. interpolation: linear|nearest|cubic. • add_method_track(player_path, animation_name, target_node_path, keyframes) Add a method track. keyframes: [{time, method, args?}, ...]. • set_autoplay(player_path, animation_name="") Set autoplay. Empty animation_name clears. • play(player_path, animation_name="") Editor preview. Not saved with scene. • stop(player_path) Stop editor preview. Not saved with scene. • list(player_path) List animations with length, loop_mode, track_count, plus libraries and autoplay. • get(player_path, animation_name) Inspect a clip's tracks and keyframes in detail. • create_simple(player_path, name, tweens, length=None, loop_mode="none", overwrite=False) High-level: build a multi-track clip from tween specs in one call. tweens: [{target, property, from, to, duration, delay?, transition?}]. • preset_fade(player_path, target_path, mode="in", duration=0.5, animation_name="", overwrite=False) One-call fade-in/out (modulate.a). • preset_slide(player_path, target_path, direction="left", mode="in", distance=None, duration=0.4, animation_name="", overwrite=False) One-call slide-in/out (position). • preset_shake(player_path, target_path, intensity=None, duration=0.3, frequency=30.0, seed=0, animation_name="", overwrite=False) One-call shake (jittered position). • preset_pulse(player_path, target_path, from_scale=1.0, to_scale=1.1, duration=0.4, animation_name="", overwrite=False) One-call pulse / hover-bounce (3-keyframe scale ping-pong).
Preset target_path: accepts either a scene-absolute path (e.g. "/Main/World/Cube",
matching every other scene tool) or a path relative to the AnimationPlayer's
root_node (e.g. "World/Cube", matching how Animation tracks store node paths).
Scene-absolute targets outside the player's root_node subtree are converted to
a ..-prefixed track path via root_node.get_path_to(target), the same shape
the relative form already accepts.
Canonical call shape: {"op": "<verb>", "params": {...}}. Flat op parameters are accepted as a compatibility alias when the client transmits them; op and session_id remain top-level.
Inputs: op (required), params, session_id. Returns: object
api_manageApi ManageA
Inspect Godot API documentation-shaped metadata from the connected editor's ClassDB: "what properties does X have", method signatures, signals, enums, constants, defaults, and property hint strings.
Resource form (prefer for active-session reads): godot://class/{class_name}
Ops:
get_class(class_name, sections=None, include_inherited=False, include_inheritors=False, offset=0, limit=100) Return selected class-reference sections without creating a scene instance. sections may be a comma-separated string or list containing properties, methods, signals, enums, constants, inheritors. Defaults to ["properties"] only — a bare get_class answers "what properties does X have" without the multi-thousand-token full dump. Pass the sections you want by name, or "all" for the full set (properties, methods, signals, enums, constants). "all" does NOT include the heavier "inheritors" section — request that by name. For pagination, request one section at a time so offset/limit apply only to the list you are paging.
Canonical call shape: {"op": "<verb>", "params": {...}}. Flat op parameters are accepted as a compatibility alias when the client transmits them; op and session_id remain top-level.
Inputs: op (required), params, session_id. Returns: object
audio_manageAudio ManageA
Sound effects, music, ambience (AudioStreamPlayer / 2D / 3D).
Bus/effect edits use global editor undo. Godot may autosave them to its active layout. bus_layout_save only exports a snapshot and does not switch that target.
Ops: • bus_list() List buses, sends, volume, mute, solo, bypass, and effect properties/enabled state. • bus_add(name, at_position=-1, send="Master") Add a uniquely named bus. -1 appends; index 0 is reserved for Master. • bus_remove(name) Remove a non-Master bus. Reroute incoming bus sends and compressor sidechains first. • bus_set(name, volume_db?, send?, mute?, solo?, bypass_effects?) Set bus properties atomically. Sends must target an earlier existing bus. • bus_effect_add(bus, effect_class, properties={}, at_position=-1, enabled=True) Insert a concrete native AudioEffect, such as AudioEffectCompressor. • bus_effect_set(bus, index, properties={}, enabled?) Edit an unscripted native effect and/or enabled state. Effect identity is preserved. • bus_effect_remove(bus, index) Remove an effect with undo of its position, properties and enabled state. • bus_layout_save(path="res://default_bus_layout.tres", overwrite=False) Export the current layout to .tres/.res. File writes are not undoable. Does not change the project default or the editor's active autosave layout. • player_create(parent_path, name="AudioStreamPlayer", type="1d") Create an AudioStreamPlayer / 2D / 3D node. type: "1d" | "2d" | "3d". • player_set_stream(player_path, stream_path) Assign an AudioStream resource (.ogg/.wav/.mp3 or .tres). Returns duration_seconds. • player_set_playback(player_path, volume_db?, pitch_scale?, autoplay?, bus?) Update common playback properties atomically. Pass only fields to change; at least one of volume_db/pitch_scale/autoplay/bus required. • play(player_path, from_position=0.0) Start real editor preview playback. Not undoable. • stop(player_path) Stop editor preview playback. Not undoable. • list(root="res://", include_duration=True) Scan project for AudioStream resources (every subclass + .tres/.res).
Canonical call shape: {"op": "<verb>", "params": {...}}. Flat op parameters are accepted as a compatibility alias when the client transmits them; op and session_id remain top-level.
Inputs: op (required), params, session_id. Returns: object
autoload_manageAutoload ManageA
Autoload (global singleton) management. Autoloads are scripts or scenes
loaded automatically at project start, accessible globally by name when
singleton=True. Persisted to project.godot.
Ops:
• list()
List autoloads with name, path, and singleton flag.
• add(name, path, singleton=True)
Register an autoload (script or PackedScene) by res:// path.
• remove(name)
Unregister an autoload by name. The underlying file is not deleted.
Canonical call shape: {"op": "<verb>", "params": {...}}. Flat op parameters are accepted as a compatibility alias when the client transmits them; op and session_id remain top-level.
Inputs: op (required), params, session_id. Returns: object
batch_executeBatch ExecuteA
Execute a list of editor sub-commands in order, stopping on first error.
Each item must be {"command": "<plugin_command>", "params": {...}}.
Use the underlying plugin command names (e.g. create_node, set_property,
delete_node, attach_script), not the MCP tool names. Commands run
sequentially; execution stops at the first error. When undo is True
(default), any successful sub-commands are rolled back via the scene's
undo history if a later sub-command fails, producing atomic-on-failure
semantics.
Use this to compose multi-step edits (create node + set property +
attach script) into a single tool call. Rollback works for sub-commands
that modify the currently edited scene. batch_execute itself is not
allowed as a sub-command.
Scene paths are relative to the edited scene root (e.g. "/Main/Enemy"), NOT runtime "/root/..." paths. The example below assumes the scene root is named "Main" — substitute the actual root name.
Inputs: commands (required), undo, session_id. Returns: object
camera_manageCamera ManageA
Camera2D / Camera3D authoring (zoom, FOV, projection, smoothing, follow).
Ops: • create(parent_path, name="Camera", type="2d", make_current=False) Create a Camera2D ("2d") or Camera3D ("3d"). When make_current=True, unmarks previously current cameras of the same class in one undo. • configure(camera_path, properties) Batch-set camera-specific properties (zoom, fov, projection, smoothing, drag, limits …). Class-aware. Enum-by-name (projection, keep_aspect, anchor_mode, doppler_tracking, process_callback). Vector2 dict coercion for zoom/offset. Transforms (position, rotation, scale, transform, global_*) live on the Node — set those via node_set_property, not here. • set_limits_2d(camera_path, left?, right?, top?, bottom?, smoothed?) Set Camera2D bounds. Pass only the edges to change. • set_damping_2d(camera_path, position_speed?, rotation_speed?, drag_margins?, drag_horizontal_enabled?, drag_vertical_enabled?) Smooth Camera2D motion (position/rotation smoothing speeds + drag deadzone). drag_margins: {left,top,right,bottom} fractions [0,1]. • follow_2d(camera_path, target_path, smoothing_speed=5.0, zero_transform=True) Reparent camera under target with smoothing — Godot-native follow. • get(camera_path="") Inspect a camera (class, current flag, all properties). Empty path resolves to the currently-active camera, falling back to the first. • list() List every Camera2D/Camera3D in the scene. • apply_preset(parent_path, name, preset, type=None, make_current=True, overrides=None) Spawn with opinionated defaults. Presets: topdown_2d, platformer_2d, cinematic_3d, action_3d. overrides merge over preset values.
Canonical call shape: {"op": "<verb>", "params": {...}}. Flat op parameters are accepted as a compatibility alias when the client transmits them; op and session_id remain top-level.
Inputs: op (required), params, session_id. Returns: object
client_manageClient ManageA
Configure AI clients to use this Godot AI MCP server. Writes / removes client config files (Claude Code, Codex, Antigravity, Cursor, Devin Desktop (Windsurf), Zed, etc.).
Ops:
• status()
List every supported client with id, display_name, status
(configured | not_configured | configured_mismatch | error),
and installed flag.
• configure(client)
Write the MCP server entry into the named client's config file.
client is one of the ids returned by status().
• remove(client)
Remove this server's entry from the named client's config.
Canonical call shape: {"op": "<verb>", "params": {...}}. Flat op parameters are accepted as a compatibility alias when the client transmits them; op and session_id remain top-level.
Inputs: op (required), params, session_id. Returns: object
csg_manageCsg ManageA
CSG authoring (create boolean shapes, set their operation).
Create CSG shapes (box, sphere, cylinder, torus, polygon) under a Node3D parent in the currently edited scene and set their boolean operation (union / intersection / subtraction) so geometry like holes, caves and tunnels can be carved directly in the editor. All write ops are undoable via EditorUndoRedoManager. Sibling CSG shapes under the same parent combine automatically; use a CSGCombiner3D parent for explicit grouping. Size, position and material live on the created node — set them with node_set_property / material_manage after creation.
Ops: • csg_create(parent_path, name="", shape="box", operation="union") Create a CSG shape under a Node3D parent (empty parent_path = scene root). shape: box | sphere | cylinder | torus | polygon. operation: union | intersection | subtraction. Returns: {path, name, shape, operation}
• csg_set_operation(path, operation) Set the boolean operation of a CSG shape. operation: union | intersection | subtraction. Returns: {operation}
Canonical call shape: {"op": "<verb>", "params": {...}}. Flat op parameters are accepted as a compatibility alias when the client transmits them; op and session_id remain top-level.
Inputs: op (required), params, session_id. Returns: object
custom_manageCustom ManageA
List or invoke custom tools registered by third-party addons.
Active session only. Use op="list" to discover registered tools. op="invoke" requires params: tool_name (string); optional: params (dict, forwarded to the addon handler unvalidated — shape per the tool's params_schema from op="list"). Inside batch_execute, address a custom tool as "custom_tool:" (deferred tools cannot run in batches). Some custom tools are also registered first-class as "custom_" with their own schema — prefer those when present.
Canonical call shape: {"op": "<verb>", "params": {...}}. Flat op parameters are accepted as a compatibility alias when the client transmits them; op and session_id remain top-level.
Inputs: op (required), params, session_id. Returns: object
editor_manageEditor ManageA
Editor selection, performance monitors, quit, log clearing, game eval.
Resource forms (prefer for active-session reads): godot://editor/state, godot://selection/current, godot://performance
Ops: • state() Editor version, project name, current scene, readiness, play state. • selection_get() Currently selected node paths in the editor. • selection_set(paths) Replace the selection with the given list of scene paths. • monitors_get(monitors=None) Performance singleton values (FPS, memory, draw calls, etc.). Pass a list of monitor names to filter; None returns everything. • quit() Gracefully quit the Godot editor on next frame. • logs_clear(clear_debugger_errors=False) Clear the MCP log buffer. Returns cleared_count. Pass clear_debugger_errors=True to also clear the Debugger dock's visible Errors-tab rows (user-facing UI, so opt-in only); the response then includes debugger_errors_cleared. • game_eval(code) Execute GDScript in the running game with return values. Uses 'await' so user code can await internally. Errors return fast and actionable: EVAL_COMPILE_ERROR for a syntax/parse error, EVAL_RUNTIME_ERROR (with the real message + line) for a runtime error; EVAL_GAME_NOT_READY if the game can't service evals — still launching (retry once it's up), the _mcp_game_helper autoload is missing/disabled, its main loop is not advancing (focus the game), or its debugger session closed; EVAL_HUNG for a live game's genuine infinite loop / never-firing await; EVAL_RESULT_TOO_LARGE if the returned value serializes past the debugger channel's capacity (return a smaller slice).
Canonical call shape: {"op": "<verb>", "params": {...}}. Flat op parameters are accepted as a compatibility alias when the client transmits them; op and session_id remain top-level.
Inputs: op (required), params, session_id. Returns: object
editor_reload_pluginEditor Reload PluginA
Reload the Godot editor plugin.
Disables and re-enables the plugin on the next frame. The response shape depends on whether this MCP server was spawned by the plugin or launched externally:
Plugin-managed (default install): returns a pre-flight ack
{status: "reload_initiated", transport_will_drop: true, old_session_id, guidance}immediately. The reload kills this server, so the WebSocket transport drops; reconnect and callsession_manage(op="list")to find the new session_id.Externally launched (e.g.
python -m godot_ai --transport streamable-http --port 8000 --reload): waits for the new session to register and returns{status: "reloaded", old_session_id, new_session_id}. If the old bridge disappears and no replacement registers within 90 seconds, raisesPLUGIN_DISCONNECTEDwithdata.reason == "reload_timeout"and recovery diagnostics.
Inputs: session_id. Returns: object
editor_screenshotEditor ScreenshotA
Capture a screenshot of the Godot editor viewport or running game.
Picking a source: the default "viewport" captures the editor's 3D
viewport, which is empty if the edited scene has no Node3D anywhere in
the tree (or no scene is open). Those cases return EDITOR_NOT_READY
with error.data = {editor_state: "viewport_not_3d", scene_root_type}
and an actionable error.message — switch to "cinematic" if the
scene has a Camera3D, or open a scene with 3D content.
Sources:
"viewport" (default): editor 3D viewport. Requires Node3D content in the edited scene (root or any descendant); see above for the no-3D-content / no-scene error shape.
"viewport_2d": editor 2D viewport. Use for 2D scenes. Not compatible with view_target/coverage/elevation/azimuth/fov.
"cinematic": render edited scene through its active Camera3D (no editor gizmos). Prefers a Camera3D marked
current; falls back to the first Camera3D found in a depth-first walk. NODE_NOT_FOUND only when the scene contains no Camera3D at all."game": running game's framebuffer (only when project is running). A backgrounded/minimized game window freezes its main loop; the capture then returns the last rendered frame with
stale_frame: trueand anotein the metadata — focus the game window and retry for a current frame.GAME_HELPER_TIMEOUTmeans the game process never replied at all (nothing rendered yet, main thread blocked, or helper dead) — focus the window and retry, or use game_command to confirm liveness.
include_image=True (default) returns an MCP ImageContent block.
view_target (comma-separated Node3D paths) reframes editor camera;
AABB metadata always returned. coverage=True with view_target
captures perspective + orthographic top-down references.
Inputs: fov, width, height, source, +10 more.
editor_stateEditor StateA
Get current Godot editor state: version, readiness, open scene, play state.
Resource form: godot://editor/state — prefer for active-session reads.
Also reachable as editor_manage(op="state") (same handler) for clients
that prefer a single rolled-up tool.
Code-mode MCP adapters keep the server and tool names separate:
call('godot-ai', 'editor_state', {}). Never pass a server-prefixed
tool name such as godot-ai/get_editor_state; that is neither the
adapter's call signature nor a registered tool. For dedicated current-
scene data, use readResource('godot-ai', 'godot://scene/current').
Side effect: refreshes the server's session readiness cache from the
live editor reply. Useful as a recovery step after a write call is
rejected as EDITOR_NOT_READY (state=playing) when you already know
the game has stopped — calling editor_state once syncs the cache
and the next write proceeds. Issue #262.
Response includes game_status for authoritative game liveness,
plus helper_live (status == "live") and session_active
(status not in {"not_live", "stopped"}) mirrored from the same fields
inside game_status. is_playing remains raw editor play-state;
use game_status.status for liveness decisions.
started_by identifies MCP versus editor launches; elapsed_s
reports run age. last_input_age_s is a sampled idle estimate,
with input_sample_age_s for freshness; null means unknown.
Godot AI injected input is excluded. Other nodes may consume input
before the helper sees it; even fresh samples do not prove device idle.
game_status.status="break" means the game process is parked in a
remote-debugger break (boot-time parse errors do this before the game
helper registers); it will not resume on its own — call
project_manage(op="stop").
Inputs: session_id. Returns: object
filesystem_manageFilesystem ManageA
Project filesystem access via the Godot editor's EditorFileSystem.
Ops:
• read_text(path)
Read a text file at a res:// path. Returns content, size,
line_count.
• write_text(path, content="")
Create or overwrite a text file. Updates the editor filesystem
entry for that one file (single-file update, not a full scan).
Newly-created files include data.cleanup.rm for transient
smoke tests; overwrite omits the field.
• import_get(path)
Read an already-imported asset's importer, options, Variant types,
writable_options, revision and native import_valid status. Validation
uses stored config types, not a full importer enum/range schema.
• import_set(path, options, reimport=True, expected_revision="")
Patch existing scalar import options for one asset. Unknown keys,
importer switching and _subresources edits are unsupported. Pass the
revision from import_get to reject stale edits. Busy scans/imports
refuse before writing. Staged replacement preserves recovery paths
on failure; file edits are non-undoable. Returns settings_committed,
import_attempted, import_pending, import_valid, import_succeeded and revision. Native
import failure after commit returns these outcomes in error data.
Native validity alone can be stale; import_succeeded also requires
no captured errors. import_diagnostics describes editor errors during
the synchronous import, not guaranteed per-asset attribution.
reimport=False saves settings only. Native import can exceed the
120-second command budget: inspect current status before retrying.
• reimport(paths)
Force-reimport imported assets via EditorFileSystem.reimport_files.
paths is a list of res:// paths.
Intended for imported assets such as textures, models, and audio.
Paths that are not imported resources (.gd scripts, .tscn,
hand-written .tres, or an asset the editor has not imported yet)
report under skipped_non_imported rather than reimported: their
filesystem entry is refreshed with update_file, but no import runs,
so a success there is not evidence that a script parsed or that
diagnostics were produced. Use
script_patch/script_create to save a script and receive fresh
diagnostics, or scan for an asset awaiting its first import.
Returns reimported, skipped_non_imported, not_found and their
counts. Failed native validity goes under failed_imports; valid paths
with captured editor errors go under unconfirmed_imports. Responses
include per-path import_status and bounded import_diagnostics.
• scan()
Force a full EditorFileSystem.scan() and wait for it to settle.
This is the headless equivalent of the editor regaining window focus:
write_text/script_create register single files but do NOT
rebuild the global class_name table, so a freshly-created
class_name MyThing extends Resource is invisible to
resource_manage/type references until a scan runs. Call this once
after adding class_name scripts when the editor isn't focused.
Single-flight (awaits any in-progress scan rather than stacking another).
Returns scan_completed and global_classes_registered_delta.
• search(name="", type="", path="", offset=0, limit=100)
Find files by name, resource type, or path substring. At least one
filter must be set. Paginated.
• move(path, new_path), rename(path, new_name)
Move a resource group with .uid/.import sidecars and preserve proven
UID references. Destination parent must exist. Literal-path owners,
project settings, open scene tabs, links and incomplete discovery are
refused before mutation; dependency rewriting is unsupported.
• remove(path, force=False, permanent=False)
Default: OS trash. Known references block unless force=True; force
never overrides incomplete discovery or protected paths. Permanent
deletion supports files only. Directory deletion uses trash.
move/rename/remove contract: Mutations require a direct call, not batch_execute. Directory results set scan_required: call scan afterward. All mutations are non-undoable. Errors report outcome unchanged/rolled_back/partial and actual affected paths. Never blindly retry a partial result.
Canonical call shape: {"op": "<verb>", "params": {...}}. Flat op parameters are accepted as a compatibility alias when the client transmits them; op and session_id remain top-level.
Inputs: op (required), params, session_id. Returns: object
game_manageGame ManageA
Runtime game inspection and input simulation.
These ops target the running game process through Godot's EngineDebugger bridge. Start the project first with project_run and poll editor_state until game_capture_ready=true.
Ops:
get_scene_tree(depth=10, root_path="") Inspect the running scene tree. root_path accepts an absolute runtime path or a scene-relative path rooted at the current scene.
get_node_info(path, include_properties=True) Inspect one running node's metadata and optional property snapshot.
get_ui_elements(root_path="", include_hidden=False, include_disabled=True, max_depth=10) Inspect visible runtime Control nodes for UI testing. Includes path, type, text where present, disabled state, and rect metadata.
suspend() Suspend the running game through Godot's native debugger path.
resume() Resume a suspended game. Idempotent when it is already running.
next_frame() Advance exactly one process tick while suspended. The response reports verification and any Embedded Game View focus handoff. Runtime-control mutations also report path="embed_signal" or "direct_session"; the direct fallback works without embedding but cannot synchronize the Game View suspend button's visual pressed state.
debug_status() Probe suspend state and the game-helper process tick counter through the debugger capture, including while SceneTree processing is suspended.
input_key(key, pressed=True, echo=False) Send a key press/release to the running game.
input_mouse(event, position=None, button="left", pressed=True, buttons=None) Send a mouse motion or button event. event: "motion" | "button". position is a {x, y} object or [x, y] array; omit it to use the game's current cursor position. A present but malformed position is rejected rather than silently falling back to the cursor. Buttons pressed through input_mouse stay held until released, and motion carries them as its button_mask with relative set from the previous mouse event, so press, motion..., release performs a GUI drag-and-drop. buttons (motion only) overrides the held set for that event, e.g. ["left"]; names: left, right, middle. Wheel steps are one-shot and never held. Button replies list the buttons held after the event; motion replies list the buttons that motion carried.
input_gamepad(device=0, control="button", index=0, pressed=True, value=0.0) Send a joypad button or axis event. control: "button" | "axis".
input_action(action, pressed=True, strength=1.0) Set a project action's pressed state directly in the running game.
input_sequence(steps, settle_frames=0) Apply a frame-timed action timeline in one call — the frame-accurate, multi-step form of input_action. Each step is {at_frame, action, pressed=True, strength=1.0}; the game applies each step's action on its scheduled frame, awaits settle_frames more, then replies once. Use this instead of separate input_action calls whenever timing matters (jump arcs, combos, walk-into-trigger): per-call network latency makes hitting a target frame impossible otherwise. Steps must be ordered by non-decreasing at_frame; frames (not ms) are the timing basis. Action-based input is focus-independent, so it works on a backgrounded game window. Cannot run inside batch_execute.
input_state(actions=None) Read current action pressed states. Empty actions = all project actions.
Canonical call shape: {"op": "<verb>", "params": {...}}. Flat op parameters are accepted as a compatibility alias when the client transmits them; op and session_id remain top-level.
Inputs: op (required), params, session_id. Returns: object
gridmap_manageGridmap ManageA
GridMap authoring (set items, fill 3D regions, clear, read cells + library items).
All operations target GridMap nodes in the currently edited scene by scene-relative path (e.g. "/Main/Terrain"). All write ops are undoable via EditorUndoRedoManager.
item is the item id from the GridMap's MeshLibrary. Use gridmap_list_library_items to discover valid ids and names before placing cells (the 3D analogue of tileset atlas inspection). orientation is the GridMap baked rotation index (0..24).
Ops: • gridmap_set_item(path, item, map_x, map_y, map_z, orientation=0) Set a single cell item at (map_x, map_y, map_z). item=-1 erases. Returns: {map_x, map_y, map_z, item, orientation}
• gridmap_fill(path, item, rect_x, rect_y, rect_z, rect_w, rect_h, rect_d, orientation=0) Fill a rect_w × rect_h × rect_d region starting at (rect_x, rect_y, rect_z) with one item in a single undo action. Returns: {cells_filled, rect: {x, y, z, w, h, d}}
• gridmap_clear(path) Remove all cells from the GridMap. Returns: {cleared: true}
• gridmap_get_used_cells(path) Return all used cell coordinates. Returns: {cells: [{x, y, z}, ...], count: int}
• gridmap_list_library_items(path) List the MeshLibrary items available to the GridMap. Returns: {library, items: [{item, name, mesh}...], count: int}
Canonical call shape: {"op": "<verb>", "params": {...}}. Flat op parameters are accepted as a compatibility alias when the client transmits them; op and session_id remain top-level.
Inputs: op (required), params, session_id. Returns: object
input_map_manageInput Map ManageA
InputMap actions and bindings (keyboard, mouse, gamepad). Persisted to
project.godot.
Resource form: godot://input_map — prefer for active-session reads.
Ops:
• list(include_builtin=False)
List input actions and their bound events. By default only
user-authored actions (those persisted in project.godot under
input/<name>) are returned; pass include_builtin=True to
also surface Godot's ui_* and editor-runtime actions
(spatial_editor/*, etc.). The is_builtin field on each
entry is true for any action not authored by the user.
• add_action(action, deadzone=0.5)
Create a new empty input action. deadzone must be in
[0.0, 1.0] — Godot uses it as the analog-stick dead-zone
threshold; values outside this range are rejected with
VALUE_OUT_OF_RANGE. Typical values are 0.2-0.5; leave the
default 0.5 unless you have a reason. Not a key-repeat delay.
• ensure_action(action, deadzone=0.5)
Idempotently create or persist an input action. If the action exists
in live InputMap or in project.godot, the existing state is preserved.
• remove_action(action)
Remove an action and all its event bindings. Also removes actions
persisted in project.godot but not loaded in the live InputMap
(loaded_in_input_map: false in list), e.g. actions created
by a previous editor session.
• bind_event(action, event_type, keycode="", ctrl=False, alt=False,
shift=False, meta=False, button=None, axis=None,
axis_value=1.0)
Bind a key/mouse/gamepad event to an action. The action must
already exist (call add_action first). event_type is
"key" | "mouse_button" | "joy_button" |
"joy_axis".
- key: keycode is a Godot keycode name string like
"A", "Space", "Enter", "Escape", "F1",
"Left" — not an integer and not KEY_*. Modifier
booleans ctrl / alt / shift / meta optional.
- mouse_button: button is an int — 1=left, 2=right,
3=middle, 4=wheel up, 5=wheel down.
- joy_button: button is the JoyButton index
(e.g. 0=A/Cross, 1=B/Circle).
- joy_axis: axis is the JoyAxis index and
axis_value is the direction/value, usually -1.0 or 1.0.
• ensure_binding(action, event_type, ...)
Idempotently ensure the action exists and has the requested binding.
Canonical call shape: {"op": "<verb>", "params": {...}}. Flat op parameters are accepted as a compatibility alias when the client transmits them; op and session_id remain top-level.
Inputs: op (required), params, session_id. Returns: object
logs_readLogs ReadA
Read recent log lines from the Godot editor, plugin, or running game.
Resource form: godot://logs/recent — prefer for active-session reads.
Sources:
"plugin" (default): MCP plugin recv/send/event traffic. Buffer 500.
"game": stdout/stderr/push_error/push_warning from playing game via
_mcp_game_helperautoload. Buffer 2000, with lines retained across runs and tagged by run_id. Default reads return current-run lines only; passsince_run_idfrom an earlier response to read that prior run. Entries: {source, level, text, run_id}; response carries run_id, current_run_id, game_status, helper_live, session_active, dropped_count, stale_run_id. helper_live and session_active mirror the same fields inside game_status; is_running is retained as a compatibility alias of session_active. Boot-time parse/load errors fire before the game helper's logger attaches, so they are NEVER in this buffer; when editor-side errors were recorded during the current run the response addseditor_errors_countandeditor_errors_hintpointing at source="editor" — treat a clean game log carrying that hint as a run that lost scripts, not a clean launch."editor": editor-process script errors and the Debugger dock's visible Errors-tab rows — parse errors, GDScript reload warnings, @tool/EditorPlugin runtime errors, push_error/push_warning. Logger-backed entries and Errors-tab rows are read from the editor UI when available. Use when the editor Output or Debugger Errors panel shows red/yellow rows but other sources turned up nothing. Buffer 500 for logger-backed entries; Debugger rows are live UI state. Entries: {source, level, text, path, line, function}. Filtered to .gd/.cs in the user project for Logger-backed entries; addons/godot_ai/ dropped. Logger entries fired before plugin enable are not captured.
"all": plugin → editor → game lines (with source per entry).
Tail pattern: for game logs, poll the current run with offset=N and
keep the returned run_id. current_run_id identifies the active run;
run_id identifies the run being read. Passing
since_run_id=old_run_id reads retained lines for that prior run, and
stale_run_id: true means the requested run is not the current run.
For editor logs, read once to capture
next_cursor and pass it back as since_cursor on later calls.
since_cursor reads Logger-backed editor entries only; live Debugger
Errors-tab rows are included in regular source="editor" reads but do
not have stable cursors. When since_cursor is set, it supersedes
offset. truncated: true means older entries fell out of the
ring before the poll; continue from the returned next_cursor and
treat oldest_cursor as the earliest retained sequence.
Set include_details=True for Errors-tab style metadata on game/editor
entries: original code/rationale, error type, resolved source, and
stack frames. Default false preserves compact responses.
Inputs: count, offset, source, session_id, +3 more. Returns: object
material_manageMaterial ManageA
Material authoring (StandardMaterial3D, ORMMaterial3D, ShaderMaterial, CanvasItemMaterial), raw shader source (.gdshader / .gdshaderinc), and VisualShader graph authoring/editing. Albedo, metallic/roughness, emission, transparency, shader uniforms, render modes.
Resource forms: godot://materials (all materials),
godot://shader/{path} (raw source + metadata),
godot://visual_shader/{path} (VisualShader graph).
Ops:
• visual_shader_create_graph(resource_path, stages, shader_type="spatial",
overwrite=False, varyings=None)
Create/save a VisualShader .tres only (not undoable). Each stages entry is
{stage, nodes: [{id, type, position?, params?}], connections:
[{from_node, from_port, to_node, to_port}]}. Explicit stages must match
spatial/canvas_item (vertex/fragment/light), particles
(start/process/collide/start_custom/process_custom), sky (sky), or fog (fog).
IDs are stage-local integers >=2 or nonempty strings; output is "output"/0.
Limits: 256 nodes, 1024 connections total. Existing destination directory
required. Returns id_map by stage as [{id, node_id}] in request order.
varyings: [{name, mode: "vertex_to_frag_light"|"frag_to_light",
type: "float"|"int"|"uint"|"vector2"|"vector3"|"vector4"|"boolean"|"transform"}]
(spatial/canvas_item only).
The generated source is parsed through the engine's shader compiler
before saving; a graph it rejects (for example a parameter named after
a shader keyword) is not written. Renderers that cannot compile a
shader type fall back to validating the generated declarations, so the
advertised modes stay accepted.
Use create(type="shader", shader_path=<saved .tres>) then assign separately.
• visual_shader_get(path)
Inspect a VisualShader .tres: shader_type, per-stage nodes (id, type,
position, params), connections, and varyings. Use before visual_shader_edit.
• visual_shader_node_catalog(filter="", offset=0, limit=100)
List instantiable VisualShaderNode classes with the properties this tool
accepts, plus legacy aliases. Discover valid node types and params before
authoring a graph.
• visual_shader_edit(resource_path, operations)
Apply a validated operation list to an existing VisualShader .tres:
add_node / remove_node / replace_node / set_node_params /
set_node_position / connect / disconnect / add_varying / remove_varying.
Operations run in order; string node ids added by the call are returned
in added and can be referenced by later operations. The whole result
is validated in memory, then saved atomically; not undoable.
• create(path, type="standard", shader_path="", overwrite=False)
Create + save a material .tres at a res:// path. type:
"standard" | "orm" | "canvas_item" | "shader". For "shader",
shader_path points to a .gdshader or VisualShader .tres.
• set_param(path, param, value)
Set a built-in property on a .tres material. Enum-valued params
accept names ("alpha" -> TRANSPARENCY_ALPHA). Color/Vector dicts.
Texture properties accept res:// paths.
• set_shader_param(path, param, value)
Set a shader uniform on a ShaderMaterial.
• get(path)
Inspect a material (type, params, uniforms, current values).
• list(root="res://", type="")
List materials under root, optional type filter.
• assign(node_path, resource_path="", slot="override", create_if_missing=False,
type="standard")
Assign a material to a node slot. Slots: "override" |
"surface_" | "canvas" | "process". When create_if_missing=True
and no resource_path, makes an inline material of type.
• apply_to_node(node_path, type="standard", params=None, slot="override",
save_to="", overwrite=False)
High-level: build + set params + assign in one undo.
save_to optionally persists to disk; errors if the file already
exists unless overwrite=True.
• apply_preset(preset, path="", node_path="", overrides=None)
Curated looks: metal, glass, emissive, unlit, matte, ceramic.
path saves to disk; node_path assigns to a node; overrides merge.
• shader_create(resource_path, code, overwrite=False, shader_type="spatial")
Create/replace a raw .gdshader (or .gdshaderinc include) from source
text. The code is parsed through Godot's shader compiler for the
declared shader type before anything is written: parse errors reject
the write with diagnostics and leave any existing file untouched.
This is parse/type validation, not a guarantee that every renderer
variant compiles. Returns shader_type, uniforms (type, hint,
hint_string, default), and cleanup hints. Not undoable.
• shader_get(path)
Read a .gdshader/.gdshaderinc: full source, shader_type, uniforms,
render modes, and #include list.
• shader_validate(code, kind="shader", shader_type="spatial", base_dir="")
Parse/type-check shader source without writing a file. Returns valid
plus errors/warnings. Pass base_dir (a res:// directory) to validate
relative #include resolution against where the shader will live.
Renderer-specific variant compilation is out of scope.
• shader_patch(path, old_text, new_text, replace_all=False)
Anchor-based edit of a shader file: exact substring match, result
revalidated before the file is replaced. Not undoable.
Canonical call shape: {"op": "<verb>", "params": {...}}. Flat op parameters are accepted as a compatibility alias when the client transmits them; op and session_id remain top-level.
Inputs: op (required), params, session_id. Returns: object
node_createNode CreateA
Create (spawn) a new node in the scene tree.
Creates a node of the given type and adds it to the parent, or
instantiates a PackedScene from scene_path. type and scene_path
are mutually exclusive — when scene_path is given, type is ignored.
Creating below an instance's internal nodes requires Editable Children to be enabled in Godot. Attaching directly to its root is supported.
Inputs: name, type, scene_file, scene_path, +2 more. Returns: object
node_findNode FindA
Find nodes in the scene tree by name, type, or group.
At least one filter must be provided. Filters AND together. Paginated.
Inputs: name, type, group, limit, +2 more. Returns: object
node_get_propertiesNode Get PropertiesA
Get properties of a node.
Resource form: godot://node/{path}/properties — prefer for
active-session reads (returns the full property set).
The default returns every editor-visible property, which can be
50-150 entries. Pass fields to return only the properties you
need — a large response-size cut on this hot read. The response
always carries total_count (all editor-visible properties)
alongside count (returned): an unfiltered call returns the full
set, so count == total_count; only the fields filter can
make count smaller. Requested names that match no
editor-visible property are listed in unknown_fields, so a
nonexistent name is distinguishable from a property that exists
with a null value.
Null-valued properties are included: an unset object/resource slot
(script on an unscripted node, an empty mesh or
material, …) returns "value": null with its declared type.
An attached script serializes to its res:// path; built-in
scripts (no resource path) fall back to their string
representation.
Inputs: path (required), fields, session_id. Returns: object
node_manageNode ManageA
Node tree manipulation (delete, duplicate, rename, reorder, reparent, groups, hierarchy reads).
Resource forms (prefer for active-session reads): godot://node/{path}/properties, godot://node/{path}/children, godot://node/{path}/groups
Ops: • get_children(path) Direct children of a node (name, type, path each). • get_groups(path) Group names the node belongs to. • delete(path, scene_file="") Remove the node. Cannot delete scene root. Undoable. • duplicate(path, name="", scene_file="") Deep-copy a node + children as a sibling. Cannot duplicate scene root. • rename(path, new_name, scene_file="") Rename a node. Sibling-name collision and "/" / ":" / "@" rules apply. • move(path, index, scene_file="") Reorder among siblings. Index 0 = first. • reparent(path, new_parent, scene_file="") Move under a new parent. Children preserved. Cannot move into descendants. • set_editable_children(path, editable, scene_file="") Explicitly enable/disable Editable Children on an instanced scene root. Undoable when changed. Ancestors are never enabled implicitly. Disabling refuses saved child overrides, nested editable instances, attachments or signals that would be lost on save. Revert those first. • add_to_group(path, group, scene_file="") Add the node to a group. • remove_from_group(path, group, scene_file="") Remove the node from a group.
All write ops accept the optional scene_file guard — if non-empty, the
mutation fails with EDITED_SCENE_MISMATCH when the editor's current scene
doesn't match.
Writes inside non-editable scene instances are rejected before mutation. Use set_editable_children explicitly or edit the source scene. Deleting, renaming, reparenting, or reordering instance-owned nodes requires editing the source scene even when Editable Children is enabled.
Canonical call shape: {"op": "<verb>", "params": {...}}. Flat op parameters are accepted as a compatibility alias when the client transmits them; op and session_id remain top-level.
Inputs: op (required), params, session_id. Returns: object
node_set_propertyNode Set PropertyA
Set a property on a node.
Overrides on an instance's internal nodes require Editable Children to be explicitly enabled; otherwise the call fails before mutation.
Verify the property name first — call node_get_properties (or read
godot://node/{path}/properties) to confirm the exact name and type
before writing. Guessing common Godot names often fails with
PROPERTY_NOT_ON_CLASS because Godot's actual properties differ from
intuition (e.g. Camera3D uses fov/current, not field_of_view;
Sprite2D uses texture, not image; Node3D uses
position/rotation/scale, not transform.origin).
Coerces value to the property's type:
Vector2/Vector3: dict with x/y/z keys.
Color: dict {r,g,b,a} or hex string ("#ff0000").
NodePath: string ("../Other/Node").
Node-typed export (
@export var target: Node2D): node path string, either a scene path ("/Main/Player") or relative to the node ("../Player"); the node's class is checked against the export's type, and the response reports the scene path. null/"" clears.Typed node array (
@export var targets: Array[Node2D]): JSON list of node path strings, each resolved and class-checked the same way; errors name the element index.Resource: res:// path string (loads + assigns); null/"" clears.
{"__class__": "BoxMesh", ...}creates a built-in resource owned by this property. After scene_save it is serialized in-place as a[sub_resource]inside the .tscn; it is not a reusable .tres. For sharing, first callresource_manage(op="create", params={"type": "BoxMesh", "properties": {...}, "resource_path": "res://meshes/box.tres"}), then pass that res:// path here (or use resource_manage(op="assign")).StringName: plain string. Array/Dictionary: JSON list/object.
PackedByteArray: JSON list of whole numbers 0..255, at most 65,536 bytes per value. [] clears. Strings, booleans, fractions and out-of-range values are rejected before mutation. Also supported inside typed containers and resource constructor properties.
Inputs: path (required), value (required), property (required), scene_file, +1 more. Returns: object
particle_manageParticle ManageA
Particle systems (GPUParticles2D/3D, CPUParticles2D/3D). All write ops create the node + sub-resources (ProcessMaterial, default QuadMesh draw pass) in a single undo action.
Ops: • create(parent_path, name="Particles", type="gpu_3d") Create an emitter. type: "gpu_3d" | "gpu_2d" | "cpu_3d" | "cpu_2d". For GPU emitters, auto-creates ProcessMaterial; for gpu_3d, also a default QuadMesh draw pass. • set_main(node_path, properties) Node-level props: amount, lifetime, one_shot, explosiveness, preprocess, speed_scale, randomness, fixed_fps, emitting, local_coords, interp_to_end. • set_process(node_path, properties) Behavior props (auto-creates ProcessMaterial for GPU). Emission shape, velocity, gravity, color_ramp, scale_curve, turbulence. See full property list in the Godot reference. GPU gravity is a Vector3 — pass {x, y, z} or [x, y, z], including for gpu_2d (the shared ProcessMaterial is 3D; z is ignored in 2D). • set_draw_pass(node_path, pass_=1, mesh="", texture="", material="") What gets drawn per particle. GPU 3D: mesh in draw_pass_N + optional material override. GPU 2D / CPU 2D: texture. CPU 3D: mesh. • restart(node_path) Restart emission. Runtime-only, not undoable. • get(node_path) Inspect main props, process material, draw passes. • apply_preset(parent_path, name, preset, type="gpu_3d", overrides=None) Curated effects: fire, smoke, spark_burst, magic_swirl, rain, explosion, lightning. One-shot presets re-trigger via restart. overrides = {"main": {...}, "process": {...}, "draw": {...}}; bare keys are auto-routed to main (amount, lifetime, one_shot, ...) or process — draw keys must be nested under "draw". draw configures the gpu_3d draw-pass StandardMaterial3D (blend_mode, albedo_color, emission, ...); on gpu_2d only draw.texture (res:// path) applies; cpu_* types reject draw overrides. Unknown or malformed override keys return INVALID_PARAMS (never silently dropped); response reports applied_main / applied_process / applied_draw. GPU gravity requires {x, y, z} (or [x, y, z]) even for gpu_2d.
Canonical call shape: {"op": "<verb>", "params": {...}}. Flat op parameters are accepted as a compatibility alias when the client transmits them; op and session_id remain top-level.
Inputs: op (required), params, session_id. Returns: object
project_manageProject ManageA
Project run/stop and project.godot settings.
Resource form: godot://project/info and godot://project/settings
— prefer for active-session reads.
Ops:
• stop()
Stop the running project (game). Takes no params — call as
project_manage(op="stop") or with params={}. Idempotent:
succeeds with was_running=false if the project isn't running.
Do NOT pass extra fields like force or reason inside
params — only the registered keys are accepted (here, none).
For multi-editor setups, pass session_id as a sibling of
op/params, not inside params.
• settings_get(key)
Read a ProjectSettings key (e.g. "application/config/name").
• settings_set(key, value)
Write a ProjectSettings key and persist to project.godot.
Refuses the startup-execution keys (autoload/*,
editor_plugins/*, application/run/main_scene,
editor/run/main_run_args, editor/script/templates_search_path);
use set_main_scene / autoload_manage(op="add") for the two
that have a validated route.
• set_main_scene(path)
Set the project's main scene — the scene project_run(mode="main")
boots and the engine loads at startup. Writes
application/run/main_scene and persists to project.godot. path
must be a res:// scene inside the project that already exists and
loads as a PackedScene, so a scaffolded project can be made runnable
without opening the generic startup-execution surface.
Canonical call shape: {"op": "<verb>", "params": {...}}. Flat op parameters are accepted as a compatibility alias when the client transmits them; op and session_id remain top-level.
Inputs: op (required), params, session_id. Returns: object
project_runProject RunA
Run (play) the Godot project from the editor.
Modes:
"main": Run the project's main scene (default).
"current": Run the currently open scene.
"custom": Run a specific scene (requires
scene).
Idempotent: if the project is already running, returns success with
data.was_already_running=true (no scene switch). To switch scenes,
call project_manage(op="stop") first, then project_run again.
After starting playback, waits briefly for the Godot AI game helper to
check in. The response includes game_status, helper_live
(status == "live"), session_active (status not in {"not_live",
"stopped"}), and any recent_errors observed during the run window.
The top-level booleans mirror the same fields inside game_status.
game_status.status="not_live" means playback launched but the game
did not become live before the helper-ready window elapsed;
"no_helper" means the project has no _mcp_game_helper autoload, as
with some headless/custom-main-loop setups (helper_live=false,
session_active=true); "stopped" means playback stopped or never
became active before liveness could be confirmed (helper_live=false,
session_active=false); "break" means the game process is parked in
a remote-debugger break — during boot this is a GDScript parse/load
error that froze the game before the helper could register, and the
response names the failing script when captured
(game_status.break = {reason, can_debug, pre_live}). A game at
a break cannot continue on its own: call project_manage(op="stop"),
fix the error, and relaunch. Poll editor_state to see late
transitions.
Inputs: mode, scene, autosave, session_id. Returns: object
resource_manageResource ManageA
Resource (asset) search, inspection, assignment, and creation. Covers generic Resource subclasses plus specialized authoring (Curve, Environment, physics shapes, gradient/noise textures).
Ops: • search(type="", path="", offset=0, limit=100) Search for resources by type or path. Type matching includes subclasses. At least one filter required. Paginated. • load(path) Inspect a .tres / .res — returns type and editor-visible properties. • inspect(node_path, property, depth=2) Read a live native resource graph without loading or modifying files. Depth 0..3; shared references, omission reasons, fixed traversal and 64 KiB encoded-result limits. Scripted/dynamic properties excluded. • assign(path, property, resource_path) Load and assign a resource to a node property. Undoable. • get_info(type) Introspect a Resource class — properties, parent, abstract flag, concrete_subclasses (for abstract bases). Read-only. • create(type, properties=None, path="", property="", resource_path="", overwrite=False) Instantiate a Resource subclass. Either path+property (assign to a node, undoable) or resource_path (save to .tres). For specific families (Curve, Environment, etc.) prefer the dedicated ops. Inline {"class": ...} constructors require Resource-typed slots or typed Resource collections. Untyped collections that discard a nested constructor are refused before saving or assigning. PackedByteArray properties accept lists of whole numbers 0..255, at most 65,536 bytes per value; [] clears. • sprite_frames_create(resource_path, animations, overwrite=False) Build saved SpriteFrames with native animations and textures. animations: [{"name":"walk","fps":8,"loop_mode":"linear","frames":[ {"texture_path":"res://sheet.png","region":{"x":0,"y":0, "width":16,"height":16},"duration":1}]}]. Omit region for a whole texture; otherwise an AtlasTexture is built explicitly. loop_mode is none, linear, or pingpong. At most 4096 animations/total frames. Unknown fields and invalid regions fail before saving. Persistent, not scene-undoable; overwrite replaces the whole resource, retaining UID. • set_properties(path, properties) Patch an existing non-imported res:// .tres/.res without resetting omitted values. Refreshes held references while preserving identity and UID. Engine built-in resources only, including nested resources. Custom scripts, GDExtension resources and resource cycles are refused. Persistent file edit, not scene-undoable. Validation/staging failures leave the original unchanged. Windows replacement retains a backup; it is not crash-atomic. Failed restoration reports recovery_backup and staged_resource paths. A rare post-save refresh failure reports disk_committed=true explicitly. • curve_set_points(points, path="", property="", resource_path="") Replace all points on a Curve / Curve2D / Curve3D. Auto-creates the curve resource if the slot is empty (curve_created flag). • environment_create(path="", preset="default", properties=None, sky=None, resource_path="", overwrite=False) Build Environment + Sky chain. Presets: default | clear | sunset | night | fog. sky may be bool or a procedural sky dict such as {"sky_material": "procedural", "sky_top_color": "#0f172a"}. Either assign to a WorldEnvironment node or save .tres. • physics_shape_autofit(path, source_path="", shape_type="") Size a CollisionShape2D/3D to a nearby visual's bounds. Searches direct siblings then parent-siblings (handles nested Body→Collision layouts). Ambiguous matches return candidate paths in error.data.candidates. Auto-creates the concrete Shape subclass if needed. shape_type accepts either the short form ("box", "sphere", "capsule", "cylinder" for 3D; "rectangle", "circle", "capsule" for 2D) or the matching Godot class name ("BoxShape3D", "RectangleShape2D", etc.). • physics_shape_generate(paths, shape_type="box", body_type="static", reparent_mesh=False, scene_file="", overwrite=False) Generate a physics body sibling (named Collider) with a CollisionShape3D for every MeshInstance3D path. Shapes are fitted in body-local space; a mesh that already has a collider sibling, a duplicate path, or a scene-root mesh is refused before anything is written. shape_type: auto | box | sphere | capsule | cylinder | convex | trimesh (or the class name for explicit shapes). Opt-in auto selects matching primitives for BoxMesh, SphereMesh, CapsuleMesh and CylinderMesh, with box bounds for every other mesh. The default remains box. Auto uses bounding fits (including tapered cylinders), not exact mesh geometry. convex/trimesh derive the shape from the mesh's own triangles, with the mesh scale baked into the shape, and are limited to 2048 triangles and 6144 vertices per mesh, with bounded mesh types (the hull build runs synchronously inside one editor-frame item); trimesh needs a static or area body, and a non-uniformly scaled parent chain refuses every type except box. body_type: static | area | rigid | character. rigid/character always wrap the mesh under the generated body (a detached dynamic body would fall away from the stationary visual); reparent_mesh=True does the same for static/area while preserving the mesh's world transform, and the reported mesh_path is then the post-move path. overwrite=True refreshes only a marked generated collider's shape and collision transform, preserving body/collision identity and user settings. Requested body type and wrapping must match; unmarked legacy bodies or broken provenance links are refused. Mixed fresh/refresh batches prepare all resources before one undo action; stale edits refuse the batch. scene_file pins the request to that edited scene. Up to 1024 paths are processed in bounded work across editor frames; inside batch_execute at most 16. The bulk write is one undo action. Returns: {created: [{mesh_path, body_path, shape_path, shape_type, body_type, operation: "create"|"refresh"}], undoable: true}. • gradient_texture_create(stops, width=256, height=1, fill="linear", path="", property="", resource_path="", overwrite=False) Build GradientTexture2D from color stops. fill: linear | radial | square. • noise_texture_create(noise_type="simplex_smooth", width=512, height=512, frequency=0.01, seed=0, fractal_octaves=0, path="", property="", resource_path="", overwrite=False) Build NoiseTexture2D wrapping FastNoiseLite. Noise types: simplex | simplex_smooth | perlin | cellular | value | value_cubic.
Canonical call shape: {"op": "<verb>", "params": {...}}. Flat op parameters are accepted as a compatibility alias when the client transmits them; op and session_id remain top-level.
Inputs: op (required), params, session_id. Returns: object
scene_get_hierarchyScene Get HierarchyA
Get the scene tree hierarchy from the open scene.
Returns a paginated flat list of nodes with name, type, path, and child count. Walks up to the specified depth.
Resource form: godot://scene/hierarchy — prefer for active-session
reads.
Inputs: depth, limit, offset, session_id. Returns: object
scene_manageScene ManageA
Scene authoring (create, save_as, close a scene tab, list open roots).
Resource form: godot://scene/current and godot://scene/hierarchy
— prefer for active-session reads.
Ops: • create(path, root_type="Node3D", root_name="") Create the initial .tscn with the given root and open it. root_name defaults to filename basename when empty. This initial root is written immediately, but later node_create/node_set_property mutations remain in editor memory until scene_save or save_as is called. • save_as(path) Save the currently edited scene to a new file path. • close(path, discard_changes=False) Close an open scene tab, e.g. a scratch/preview scene, so its file can then be moved or removed. Refused when the tab has unsaved changes unless discard_changes=True (those edits are lost). Closing another tab brings the current one back to the front; previous_scene_restored in the result says whether that worked. Accepts res:// or uid://. Not undoable. • get_roots() List scenes currently open in the editor; flag the edited one.
Canonical call shape: {"op": "<verb>", "params": {...}}. Flat op parameters are accepted as a compatibility alias when the client transmits them; op and session_id remain top-level.
Inputs: op (required), params, session_id. Returns: object
scene_openScene OpenA
Open an existing scene file (.tscn) in the editor.
If path is already the currently edited scene this is a no-op
— the in-memory state (including any unsaved MCP mutations) is
preserved. Pass force_reload=True when the file on disk is the
authority and the editor should discard the open in-memory copy and
re-read the scene from disk.
The reply is sent only after the editor has actually switched to the
requested scene (switched: true), so follow-up writes are safe
immediately. switched: false with settle: "timeout" means the
switch had not landed within the wait window. In synchronous contexts
(e.g. inside batch_execute) the reply returns immediately with
switched: false and settle: "not_waited". In both of those
cases, re-check editor_state before issuing follow-up writes.
Inputs: path (required), session_id, force_reload. Returns: object
scene_saveScene SaveA
Save the currently edited scene to disk.
Node and property mutation tools change the editor's in-memory scene; call this explicitly to persist those mutations to the existing path.
Inputs: session_id. Returns: object
script_attachScript AttachA
Attach a script to a node in the scene tree.
Replaces any existing script on the node. Undoable.
Inputs: path (required), script_path (required), session_id. Returns: object
script_createScript CreateA
Create a script file on disk: GDScript (.gd, validated) or C# (.cs, text only).
Writes content to the path. Overwrites if it exists. Registers the
file with the editor. New files include data.cleanup.rm listing
the file and, when supported by the editor, its .uid sidecar;
overwrite omits it.
.gd: source is parse-validated and the response carries
diagnostics (diagnostics_status="checked"); an already-loaded
script is refreshed in place. .cs: written as text only — Godot AI
does not compile .NET, so diagnostics_status="not_checked" and
validation_hint says to build the project (editor Build button
or dotnet build) to see compiler errors. dotnet_editor
reports whether the connected editor build has .NET at all. Any
other extension is rejected; use filesystem_manage op="write_text".
Inputs: path (required), content, session_id. Returns: object
script_manageScript ManageA
Script (.gd / .cs) reading, detachment, and outline.
Resource form: godot://script/{path} — prefer for active-session reads.
Ops:
• read(path)
Read full source, line count, file size.
• detach(path)
Remove the currently attached script from a node. Undoable.
• find_symbols(path)
Outline a script. .gd: class_name, extends, functions, signals,
@export vars. .cs: class, base type, methods, [Signal] delegates,
[Export] members. Response language says which parser ran.
Language support: GDScript is the full contract. C# (.cs) is text-only —
files are written, read and outlined, but Godot AI does not build .NET or
report C# compiler errors; inspect the editor Build panel or dotnet build
terminal output. logs_read does not capture .NET compiler output.
Canonical call shape: {"op": "<verb>", "params": {...}}. Flat op parameters are accepted as a compatibility alias when the client transmits them; op and session_id remain top-level.
Inputs: op (required), params, session_id. Returns: object
script_patchScript PatchA
Anchor-based string-replace edit on a .gd or .cs file.
Finds an exact old_text and replaces with new_text. Fails
on multiple matches unless replace_all=True; fails on zero matches.
Exact byte match (whitespace significant). Triggers filesystem scan.
.gd: parse-validated (diagnostics) and an already-loaded GDScript
is refreshed in place so the next call runs the new code (response
reloaded=true; otherwise reload_reason says why). .cs: text only —
diagnostics_status="not_checked", reload_reason= "csharp_requires_build"; rebuild the .NET assembly to run it.
Not undoable via Ctrl+Z.
Inputs: path (required), new_text (required), old_text (required), session_id, +1 more. Returns: object
session_activateSession ActivateA
Set the active Godot editor session for subsequent tool calls.
Accepts either an exact session_id or a substring hint matched against the session's short name (project folder basename), project_path, or session_id. An exact id match always wins; a substring must resolve to exactly one session or the tool returns an error listing the candidates.
Inputs: session_id (required). Returns: object
session_manageSession ManageB
Session listing.
Resource form: godot://sessions — prefer for resource-aware clients.
Ops:
• list()
List every connected Godot editor with metadata: session_id, short
name, godot_version, project_path, plugin_version, server_version,
editor_pid, server_launch_mode, current_scene, play_state, readiness,
connected_at, last_seen, is_active. The response also carries the
server-global exclude_domains (tool domains not registered on
this server via --exclude-domains).
Canonical call shape: {"op": "<verb>", "params": {...}}. Flat op parameters are accepted as a compatibility alias when the client transmits them; op and session_id remain top-level.
Inputs: op (required), params, session_id. Returns: object
signal_manageSignal ManageA
Signals (Godot's event/observer mechanism) — list, connect, disconnect.
Ops:
• list(path, include_editor=False)
List all signals on the node and their current connections (built-in
and custom). By default editor-internal connections (the
SceneTreeEditor dock and friends) are filtered out — pass
include_editor=True to surface them. The response carries
editor_connection_count so an agent can tell how many were hidden.
• connect(path, signal, target, method)
Connect a signal from path to a method on the target node.
Undoable.
• disconnect(path, signal, target, method)
Remove an existing connection. Undoable.
Canonical call shape: {"op": "<verb>", "params": {...}}. Flat op parameters are accepted as a compatibility alias when the client transmits them; op and session_id remain top-level.
Inputs: op (required), params, session_id. Returns: object
test_manageTest ManageA
Test result inspection (re-fetches the most recent test_run payload).
Resource form: godot://test/results — prefer for active-session reads.
Ops: • results_get(verbose=False) Same shape as test_run — full results from the last run, no re-execution. verbose=True includes every individual test result.
Canonical call shape: {"op": "<verb>", "params": {...}}. Flat op parameters are accepted as a compatibility alias when the client transmits them; op and session_id remain top-level.
Inputs: op (required), params, session_id. Returns: object
test_runTest RunA
Run GDScript test suites inside the connected Godot editor.
Discovers test_*.gd in res://tests/, instantiates them, and runs
all test_* methods. Returns a compact summary by default (counts,
suite names, duration) plus failures only. verbose=True includes
every individual test result (each with per-test duration_ms).
Preloaded GDScript dependencies may remain stale after source edits; the response includes cache_warning. Restart the editor before using a rerun to validate dependency edits. ResourceLoader cache modes alone do not refresh the GDScript preload cache.
The whole run has a 300s budget; the plugin aborts between tests shortly before it expires and returns TEST_RUN_TIMEOUT with the partial summary (full partials via test_manage(op="results_get")). Long suites are safe — the editor services the MCP transport between tests — but one single test blocking the main thread for 20s+ can still drop the session. Not allowed inside batch_execute.
The response includes edited_scene (the scene currently open in
the editor). Many suites assume the project's main scene is open; if
it is not and there are failures, the response also carries a
scene_warning — open the main scene (scene_open) and re-run
before treating those failures as real.
Inputs: suite, verbose, test_name, session_id, +1 more. Returns: object
theme_manageTheme ManageA
Theme authoring (Godot's stylesheet-like resource for Controls). Cascades down a Control subtree when assigned via theme_apply.
Stylebox numeric fields (border widths, corner radii, margins, shadow) must be finite numbers and stylebox flags (anti_aliasing, draw_center) must be real booleans; a non-numeric or non-finite value is refused with a structured error before anything is applied, so a refused call leaves the theme and undo history untouched.
Slot changes are persisted immediately: if the theme file cannot be written the call fails with an error, the previous slot is restored, and no undo entry is committed.
Ops (pass via op="..." plus a params dict):
• create(path, overwrite=False)
Create a new empty Theme .tres at a res:// path.
• set_color(theme_path, class_name, name, value)
Set a color slot. value: "#rrggbb"/"#rrggbbaa", named, or
{"r","g","b","a"}.
• set_constant(theme_path, class_name, name, value)
Set an integer constant (separation, margin, padding).
• set_font_size(theme_path, class_name, name, value)
Set a font_size slot in pixels.
• set_stylebox_flat(theme_path, class_name, name, bg_color?, border_color?,
border?, corners?, margins?, shadow?, anti_aliasing?)
Compose a StyleBoxFlat (panels, button states, line edits).
border/corners/margins/shadow each accept "all" + per-side keys.
• set_stylebox_texture(theme_path, class_name, name, texture_path,
region?, margins?, axis_stretch_horizontal?,
axis_stretch_vertical?, modulate_color?, draw_center?)
Compose a 9-slice StyleBoxTexture from an imported image — pixel-art
buttons and artwork-backed panels. region is {position, size} or
[x,y,w,h]; margins are {all|left|top|right|bottom}; axis stretch modes
are "stretch" | "tile" | "tile_fit".
• set_font(theme_path, class_name, name, font_path)
Assign a Font resource (FontFile .ttf/.otf, FontVariation) to a font
slot. Loads the imported resource from res://.
• set_icon(theme_path, class_name, name, texture_path)
Assign a Texture2D to an icon slot (checkbox marks, dropdown arrows).
• stylebox_override(path, slot, patch)
Per-node stylebox override: duplicate the stylebox the Control
resolves for slot, apply a StyleBoxFlat patch (same keys as
set_stylebox_flat; unknown top-level keys are refused), and attach it
via add_theme_stylebox_override. The action lands in the scene's undo
history, so the editor's scene undo restores the previous override or
removes it. The zero-border angular-frame / flash-the-bar-bg pattern
without mutating the theme.
• apply(node_path, theme_path="")
Assign the theme to a Control (cascades to descendants). Empty
theme_path clears.
All ops accept session_id on the wrapper to target a specific editor.
Canonical call shape: {"op": "<verb>", "params": {...}}. Flat op parameters are accepted as a compatibility alias when the client transmits them; op and session_id remain top-level.
Inputs: op (required), params, session_id. Returns: object
tilemap_manageTilemap ManageA
TileMap / TileMapLayer authoring (set tiles, fill rects, clear, read cells).
All operations target TileMapLayer nodes in the currently edited scene by scene-relative path (e.g. "/LavaLake20x20/Ground"). All write ops are undoable via EditorUndoRedoManager.
source_id is the TileSet source index. atlas_col/atlas_row are the atlas coordinates of the tile within that source. For full-tile animated sources (lava, water, sewage) use atlas_col=0, atlas_row=0.
IMPORTANT — Source-ID remapping in specialized .tres files: When a layer uses a specialized .tres (e.g. volcano_animated.tres), Source-IDs are re-numbered from 0. Example: volcano lava is Source 8 in the main volcano.tres but Source 0 in volcano_animated.tres. Always use the remapped ID when the TileMapLayer references a specialized .tres, not the original ID from the main .tres.
Ops: • tilemap_set_cell(path, source_id, atlas_col, atlas_row, map_x, map_y) Set a single tile at (map_x, map_y). Returns: {map_x, map_y, source_id, atlas_col, atlas_row}
• tilemap_set_cells_rect(path, source_id, atlas_col, atlas_row, rect_x, rect_y, rect_w, rect_h) Fill a rect_w × rect_h region starting at (rect_x, rect_y) with one tile type in a single undo action. Returns: {cells_filled, rect: {x, y, w, h}}
• tilemap_clear(path) Remove all tiles from the layer. Returns: {cleared: true}
• tilemap_get_cells(path) Return all used cell coordinates. Returns: {cells: [{x, y}, ...], count: int}
Canonical call shape: {"op": "<verb>", "params": {...}}. Flat op parameters are accepted as a compatibility alias when the client transmits them; op and session_id remain top-level.
Inputs: op (required), params, session_id. Returns: object
tileset_manageTileset ManageA
TileSet management — atlas inspection tools.
Ops: • tileset_create_atlas(resource_path, texture_path, tile_size, tiles, source_id=0, margins=None, separation=None, overwrite=False) Build a saved TileSet with one native atlas source. tile_size is {x,y} in pixels and sets both TileSet tile size and atlas cell size. tiles is [{"coords":{"x":0,"y":0},"size":{"x":1,"y":1}}]; size defaults to one cell. margins/separation are {x,y} pixel offsets, default zero. At most 4096 nonoverlapping tiles, all within the texture. No terrain, collision, animation or alternative-tile configuration is performed. Persistent, not scene-undoable. overwrite replaces the whole TileSet while retaining UID. Use existing atlas read ops to inspect the result.
• tileset_get_atlas_tiles(tileset_path, source_id) Return all occupied atlas tile positions for one source in a TileSet. Read-only — does not modify any resource or project file.
tileset_path: res:// path to the .tres TileSet resource (required)
source_id: raw TileSet source id of the TileSetAtlasSource to query (required, ≥ 0)
Returns:
{"tiles": [{"col": int, "row": int}, ...], "count": int}
Error codes (passed through from GDScript handler):
MISSING_REQUIRED_PARAM — tileset_path empty or source_id absent
RESOURCE_NOT_FOUND — tileset_path does not exist on disk
WRONG_TYPE — not a TileSet, or source is not a TileSetAtlasSource
VALUE_OUT_OF_RANGE — source_id does not exist in this TileSet• tileset_get_atlas_image(tileset_path, source_id, max_size=0) Return the atlas sprite-sheet texture of a TileSetAtlasSource as a Base64-encoded PNG image. Read-only — reads the texture directly from the resource without any UI interaction.
tileset_path: res:// path to the .tres TileSet resource (required)
source_id: raw TileSet source id of the TileSetAtlasSource to query (required, ≥ 0)
max_size: optional int; if > 0, scale the image so its longest
edge is at most max_size pixels (default 0 = full res)
Returns:
{"image_base64": str, "width": int, "height": int,
"original_width": int, "original_height": int, "format": "png"}
Error codes (passed through from GDScript handler):
MISSING_REQUIRED_PARAM — tileset_path empty or source_id absent
RESOURCE_NOT_FOUND — tileset_path does not exist on disk
WRONG_TYPE — not a TileSet, source not a TileSetAtlasSource,
or source has no texture assigned
VALUE_OUT_OF_RANGE — source_id does not exist in this TileSet• Atlas image workflow: To visually inspect what tiles look like, use tileset_get_atlas_image instead of editor screenshots. It reads the texture directly from the resource — no UI interaction or editor state required.
Canonical call shape: {"op": "<verb>", "params": {...}}. Flat op parameters are accepted as a compatibility alias when the client transmits them; op and session_id remain top-level.
Inputs: op (required), params, session_id. Returns: object
ui_manageUi ManageA
UI / Control authoring (HUD, menus, layouts, vector decoration).
Ops:
• set_anchor_preset(path, preset, resize_mode="minsize", margin=0)
Apply a Control layout preset. preset: top_left | top_right |
bottom_left | bottom_right | center_left | center_top | center_right |
center_bottom | center | left_wide | top_wide | right_wide |
bottom_wide | vcenter_wide | hcenter_wide | full_rect.
resize_mode: minsize | keep_width | keep_height | keep_size.
Target must be a Control. CanvasLayer is the canonical HUD parent
but is not a Control — put a Control child under the CanvasLayer and
apply the preset to that overlay.
• set_text(path, text)
Set text on a Label/Button/LineEdit/TextEdit/RichTextLabel.
• set_richtext(path, text, bbcode=True)
Set a RichTextLabel's text with BBcode parsing on by default —
"[color=red]HP[/color]" renders as markup, and bbcode=False writes
literal text. Undoable.
• build_layout(tree, parent_path="")
Atomically build a UI subtree from a nested spec
({type, name?, properties?, anchor_preset?, anchor_margin?, theme?,
children?}). Validates everything before mutating.
properties is direct node properties only. Theme constants like
container spacing live under theme_override_constants/<name> —
e.g. {"theme_override_constants/separation": 8} on a
VBoxContainer, not {"separation": 8} (which errors).
theme and anchor_preset require a Control / Window — for a HUD,
nest a Control under a CanvasLayer and apply them to the Control
child, not the layer itself.
• draw_recipe(path, ops, clear_existing=True)
Attach a declarative list of vector _draw() ops to a Control —
radar sweeps, gauges, corner brackets, crosshairs, waveforms.
Op kinds: line | rect | arc | circle | polyline | polygon | string.
Canonical call shape: {"op": "<verb>", "params": {...}}. Flat op parameters are accepted as a compatibility alias when the client transmits them; op and session_id remain top-level.
Inputs: op (required), params, session_id. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 47 tools
Many tools target clearly distinct Godot domains, but several paired tools blur boundaries: editor_state duplicates editor_manage(op="state"), scene_get_hierarchy overlaps node_manage get_children and game_manage get_scene_tree across editor/runtime, animation_create overlaps animation_manage clip creation, and test_run/test_manage are two halves of the same workflow. Descriptions help, but the 47-tool surface creates real misselection risk.
All names are snake_case and readable, but they mix several conventions: many domain_manage wrappers (audio_manage, node_manage, resource_manage) alongside dedicated verb_noun tools (node_create, script_patch, scene_open) and noun-only tools (editor_state, test_run, batch_execute). The pattern is understandable but not a single predictable convention.
47 tools is well beyond the typical 3-15 range and past the 25+ threshold where the surface becomes heavy. Godot is a broad domain and the *_manage wrappers consolidate many operations, but the overall tool count still imposes a high selection cost.
The surface covers an unusually broad Godot editor workflow: scenes, nodes, scripts, resources, filesystem, animation, audio, tilemap/gridmap, materials/shaders, particles, cameras, UI/theme, runtime game inspection and input, tests, logs, sessions, and batch execution. Minor gaps remain, such as broader TileSet terrain/collision/animation configuration and project export, but core CRUD and lifecycle paths are largely present.
Maintenance
Related MCP Connectors
Make games with AI: one MCP server that connects your agent to Unity, Unreal and Godot editors.
Connect AI agents to Flato's editable canvas runtime through a hosted MCP server.
Connect AI clients to your Dactic work context through a hosted MCP service.
The OpenRouter MCP server plugs OpenRouter into the AI tools you already use. Once connected, your assistant can pull live OpenRouter data (models, prices, your credits, rankings, and docs) and send quick test messages, all without leaving your editor.
Related MCP Servers
- AlicenseCqualityCmaintenanceEnables AI-driven game development by providing MCP tools to interact with the Godot editor, including scene editing, node manipulation, script attachment, and scene execution.2814 npmMIT
- AlicenseAqualityDmaintenanceProvides AI assistants with tools to launch the Godot editor, run projects, manipulate scenes, manage scripts, and control node properties through a standardized MCP interface.21MIT
- AlicenseBqualityCmaintenanceConnects MCP-capable AI clients to a running Godot 4 editor for scene, node, project, and debug runtime operations via a local-first architecture.361MIT
- FlicenseAqualityBmaintenanceMCP server that connects AI coding assistants to a live Godot editor, enabling scene, node, script, resource, runtime, debugger, and test workflows through natural language.45-