Godot MCP Loop

Undo the most recent edits made through this MCP server (node, property, script changes), newest first. Stops without touching anything if a human made a later edit in the same history.

Open the Godot editor on the current project and wait until the MCP Loop bridge answers, then return the same fields as godot_status. Does nothing when an editor already runs for the project. Godot is found from the server's --godot / GODOT_BIN, else PATH and the usual install folders (4.5+ required). The project needs the MCP Loop addon installed and enabled. headless: true opens it without a window (no screenshots; for servers and CI). The editor keeps running after the server stops; editor_quit closes editors opened here.

Close the Godot editor of the current project — only one this server opened with editor_launch (an editor the user opened is refused with EDITOR_NOT_LAUNCHED). Stops a running game, saves the open scenes unless save: false, quits, and waits for the process to end (stopped with SIGTERM after timeout_ms).

Create, overwrite or partially edit a text file in the project: .yaml/.yml (e.g. scenarios), .json, .md, .txt, .csv. Give 'content' for the whole file or 'edits' (exact replacements, like script_edit). YAML syntax is checked before writing and scenario files are validated (warnings); JSON must parse. Undoable with edit_undo. Use script_write for .gd files.

Call a method on a node in the running game (e.g. a test hook such as restart() or spawn_wave(3)) and return its result. Arguments are converted to the declared parameter types; coroutines are awaited.

List a RigidBody3D's contact points, normals and the bodies they touch (contact_monitor must be on), so grounding can be read instead of inferred from a picture.

Check whether a Node3D is inside the camera's view (not behind it, projected inside the viewport) and where it lands on screen — the 3D judgement that otherwise needs a screenshot.

Play a sequence of input steps in the running game (actions, keys, mouse), in order and with real timing; hold_frames/wait_frames count physics frames for deterministic timing. Inline set/call/assert/wait_for steps run inside the game between inputs with no time passing, so one call can set up, act and check (a failing step aborts and releases held input). Returns when the whole sequence has finished. To observe something brief (e.g. the top of a jump), pass 'record': the properties are sampled every frame while the steps run, and min/max (with times) are returned. min/max are computed from every recorded frame (up to 3000 frames); only the returned sample list is thinned to 50 entries, so interval_ms is not needed for accuracy. Add a final {wait_ms} step to keep recording after the input ends. Set pause_at_end to leave the game paused when the sequence finishes, so the next call measures the state the input left behind instead of a later one.

Pause (paused: true) or resume the running game. While paused, game nodes don't run but game_query, game_set, game_call and game_wait_for still work — inspect and set up a situation across several calls without time passing, then advance with game_step. Input sent with press: true stays held while stepping.

Read live state from the running game. With 'properties' returns those values (supports 'position:x'); without, returns the node's class, children and common properties plus script variables. It only reads properties: to call a method use game_call.

Cast a ray between two world-space points and return the hit position, normal, distance and collider (or hit: false). World axes do not follow a body's rotation, unlike a child RayCast3D.

Launch the game from the editor and wait until the MCP runtime inside it is connected. Script errors in the game are logged and auto-continued unless pause_on_error=true.

Change state in the running game, e.g. to set up a test: {"score": 300, "position:x": 40, "items:2": 5}. Paths may address members, array elements and dictionary keys. Values are converted to the existing type; all of them are validated first and nothing changes if one is invalid. Returns before/after per path.

Run exactly N physics frames, then leave the game paused (pauses it first if needed). Deterministic: every pausable node gets the same N _physics_process calls, independent of call latency. press/release/tap are sent just before the first stepped frame, like real input, so the game sees them in that frame as Input.is_action_just_pressed() and as input events (tap lasts one frame) — input sent with game_input while paused can't do that.

Stop the running game. Its logs stay readable with logs_read(source='game').

Walk the Control nodes of the running game and report layout problems: Controls with no size, Controls outside the viewport or beyond their parent panel, text that needs more room than its rect (clipped) and overlapping labels. Returns the tree (path, class, rect, size, anchors, text) plus the issues, so a HUD can be checked without reading a screenshot.

Wait until a property of a node in the running game (or the return value of one of its methods, e.g. {method: 'summary', property: 'state'}) satisfies a condition, checked every frame. Fails with TIMEOUT and the last observed value. timeout_ms=0 checks once (an assertion). op changed/increased/decreased waits for a change from the value seen when waiting starts.

Check the connection to the Godot editor and get basic state: Godot version, project name, currently edited scene and whether the game is running. Call this first.

Create a PNG sprite from text, NES-style: 'palette' maps single characters to colors and each string in 'rows' is one row of pixels ('.' and ' ' are transparent). 'frames' (a list of row lists) makes a horizontal sprite sheet for animation. Scaled with nearest neighbour, imported immediately, undoable with edit_undo. Use the result as {"res": path} for a Sprite2D texture.

Add or replace an input action in the project's input map (project.godot), or remove it with remove: true. Keys are matched by physical position (e.g. 'A', 'Space', 'Left', 'Shift'). Undoable with edit_undo. A running game picks up changes after game_run with restart: true.

Read captured output: prints, errors and warnings (with file/line and stack when available). source='game' (default; kept after the game stops) or 'editor'. Pass the returned 'next' as 'since' to read only new entries.

Add a node to the edited scene (undoable). Provide either 'type' (a class like 'Sprite2D') or 'scene' (a res:// .tscn to instance). Initial properties are validated before anything is changed. Value formats: Vector2/3 as [x, y(, z)] or {x, y}; Color as '#rrggbb', '#rrggbbaa', a name like 'red', or [r, g, b, a] in 0..1; NodePath/StringName as strings; Rect2 as [x, y, w, h]; resources as {"res": "res://path"} for a file, or {"new": "RectangleShape2D", "properties": {"size": [32, 48]}} to create an embedded one (shapes, materials, styles; not scripts); null clears. Nested fields can be set with Godot's indexed syntax, e.g. "position:x".

Delete a node and its children from the edited scene (undoable with edit_undo). The scene root cannot be deleted.

Read properties of a node in the edited scene. By default returns only properties that differ from the class default plus script variables.

Set one or more properties on a node as a single undoable action. All values are validated first; nothing changes if any is invalid. Returns before/after values. Value formats: Vector2/3 as [x, y(, z)] or {x, y}; Color as '#rrggbb', '#rrggbbaa', a name like 'red', or [r, g, b, a] in 0..1; NodePath/StringName as strings; Rect2 as [x, y, w, h]; resources as {"res": "res://path"} for a file, or {"new": "RectangleShape2D", "properties": {"size": [32, 48]}} to create an embedded one (shapes, materials, styles; not scripts); null clears. Nested fields can be set with Godot's indexed syntax, e.g. "position:x".

Point this running server at another Godot project, so the following tool calls work on it — one MCP registration for many games. Only projects below the folders given with --projects-root are allowed (without it the server stays on its --project). Returns the new project's status like godot_status, or, when no editor is open for it, how to open one. The previous project's editor and game keep running. Don't switch while another tool call runs.

Export the project with one of its export_presets.cfg presets (Godot's `--export-release`, headless, fixed argument list, no shell). The output always goes under res://build/ — pass `path` to choose the name, or omit it for res://build/<preset>/ (index.html for Web). Returns the files written with their sizes, plus the tail of Godot's log. Fails with TEMPLATES_MISSING when Godot has no export templates installed. `dry_run` shows the command and the target without exporting.

Project overview: name, main scene, autoloads, input actions and their events (Godot's built-in ui_* actions are hidden unless include_builtin_actions), and (optionally) a file list filtered by a glob.

List the Godot projects this server may switch to: folders with project.godot below the --projects-root folders (up to 3 levels down, hidden folders skipped), each with its name, whether the MCP Loop addon is installed, whether an editor is running for it, and which one is current. Use project_connect to switch.

Change one project setting from a fixed list: the main scene, the viewport size, the window size override, the stretch mode/aspect, the project name and max_fps. Anything else (rendering, physics, autoloads, input map) is refused — use the editor. Values may be sent as strings. Undoable with edit_undo; the editor window and a running game pick most settings up when they start.

Run a scripted play-test: (re)start the game, then execute steps in order — wait_for, assert, input, query, screenshot, wait_ms, assert_no_errors, set, call, repeat — stopping at the first failure. Returns a summary with per-step result, what was checked and the observed value, game errors, and screenshots; report='full' adds the JSON report. Pass a YAML/JSON file in the project (path), a folder or a list of files (paths) to run several and get one summary, or an inline scenario. save_to keeps the screenshots and a report as files in the project. movie records every frame with Godot's Movie Maker (fixed frame rate, needs a game window) and saves movie.gif plus contact.png — a grid of evenly spaced frames, also returned as an image so you can see the motion.

Create a new scene file with a single root node and open it. Fails if the file already exists.

Open a scene in the editor and make it the edited scene. Subsequent node_* tools operate on it.

Save the currently edited scene to disk.

Node hierarchy of the edited scene: name, class, relative path, attached script and instanced scene for each node.

Capture an image of the running game (target='game', default) or of the editor's 2D/3D viewport (target='editor'). Game captures are scaled to the project's viewport size (normalize='viewport') so repeated screenshots compare like for like; pass normalize='none' to keep the window size. The text says the size and, when it differed, the window size. Not available when running headless.

Attach an existing script to a node in the edited scene (undoable). Pass script=null to detach.

Change part of an existing GDScript file by exact text replacement, without resending the whole file. Each edit's 'old' must match exactly once (including indentation; GDScript uses tabs) unless replace_all is set; edits apply in order. The result is compiled first; on errors or a non-matching edit nothing is written. Returns a unified diff. Undoable with edit_undo.

Read a text resource inside the project (GDScript, shader, .tscn, .cfg ...).

Create or overwrite a GDScript (.gd) file. The code is compiled first; on errors nothing is written and the errors (with line numbers) are returned. Returns a unified diff for changed files and a one-line summary for new ones. Undoable with edit_undo. For small changes to an existing file prefer script_edit.

Run the project's unit tests with GUT or GdUnit4 (whichever is installed in addons/) in a separate headless Godot process started by the editor, and return pass/fail counts, every failing test with its message, and errors from the log. Use it for game logic; use scenario_run for play. Failing tests are a normal result (not a tool error).