Godot MCP

Launch the Godot editor GUI for a project. Does not run the game — use run_project or run_interactive for that.

Run the Godot project non-interactively and capture console output. No input, screenshots, or state queries — use run_interactive for those.

Get console output (stdout/stderr) from a running Godot project. Supports errors_only and tail filters. For structured errors with stack traces, use get_runtime_errors.

Stop the currently running Godot project. Does not affect the editor launched via launch_editor.

Get the installed Godot version

List Godot projects in a directory

Retrieve metadata about a Godot project

Create a new Godot scene (.tscn) file with a root node. Specify rootNodeType (e.g., 'Node2D', 'Node3D', 'Control'; defaults to 'Node2D').

Add a child node to a scene file on disk. Defaults to root if parentNodePath is omitted. For sub-scene instances, use instantiate_scene.

Load a sprite into a Sprite2D node

Export a scene as a MeshLibrary resource

Save a scene file, optionally to a new path via newPath (creating a copy). Most editing tools save automatically; use this primarily for saving copies.

Set tile cells on a TileMapLayer node in a scene

Read a scene's node tree from a .tscn file on disk as JSON (names, types, properties, hierarchy). No running game required. For architecture analysis, use get_scene_insights.

Set properties on a node in a saved scene file (.tscn) on disk permanently. For live runtime changes, use set_property instead.

Attach a GDScript file to an existing node in a scene

Create a .tres resource file with typed properties

Modify project.godot settings (input actions, display, rendering, physics, etc.). For autoload singletons, prefer manage_autoloads.

Remove a node (and its children) from a scene

Move a node to a different parent within the same scene

Connect a signal from one node to a method on another node in a scene file (.tscn) on disk. For runtime signal monitoring, use subscribe_signals or send_key_sequence.

Read existing tile cells from a TileMapLayer node in a scene

Create a TileSet resource with atlas sources from texture files

Export a Godot project for a target platform using a configured export preset

Validate a scene for common issues (missing scripts, broken references, orphan nodes)

Execute multiple scene operations in a single Godot process invocation. Much faster than individual tool calls since each spawns a separate process. Use for 3+ operations.

Get the UID for a specific file in a Godot project (for Godot 4.4+)

Update UID references in a Godot project by resaving resources (for Godot 4.4+)

Add a node to one or more groups in a scene

Remove a node from one or more groups in a scene

Add a scene as a child instance of another scene (e.g., spawn a player scene inside a level)

Add an animation with tracks and keyframes to an existing AnimationPlayer node. To create the AnimationPlayer itself, use create_animation_player first.

Read the contents of a GDScript file from a Godot project. Returns the full source code as text.

Write or overwrite a GDScript file in a Godot project. Creates parent directories if needed. Use validate_script afterward to check for syntax errors.

Set custom data layer values on specific tile cells in a TileMapLayer

Duplicate a node within a scene, optionally with a new name or different parent

Rename a node in a scene file. Updates the node's name while keeping all properties, children, and connections intact.

Read properties from a node in a saved scene file (.tscn) on disk. Returns all non-default properties, or specific ones if listed. For runtime properties, use evaluate_expression.

Create an AnimationPlayer node in a scene with optional pre-configured animations. To add animations to an existing player, use add_animation.

Add, remove, or list autoload singletons in project.godot

Set collision layer and/or mask on a physics node. Accepts layer numbers (1-32) as array or raw bitmask.

Render a scene file statically and save the viewport as a PNG. No running game needed. For live game captures, use game_screenshot or run_and_capture. Requires a display server.

Run the project for a duration, capture a screenshot, then stop. Runs the full game (unlike capture_screenshot) without needing run_interactive (unlike game_screenshot). Requires a display server.

Send a single Godot InputMap action (e.g., 'move_up', 'jump') to a running interactive project. Returns delivery confirmation only, not the effect — for multi-step testing prefer send_key_sequence with {"action": ...} items, which batches inputs, waits, and state/screenshot checkpoints into one roun…

List all input actions defined in a project's project.godot (the InputMap). Useful before using send_input. No running game required.

Run a Godot project with MCP input receiver injected. Enables send_key_sequence (batched inputs + checkpoints), game_state, get_runtime_errors, and screenshots via TCP. Use instead of run_project for interactive testing.

Fast structured verification (preferred over game_screenshot for gameplay logic): returns current scene name, script variables of all autoload singletons, and Player position if a Player node exists. For state not exposed via autoloads, use evaluate_expression or get_node_properties. For inline stat…

Invoke a method on a live node in a running interactive Godot project. Resolves the node by path relative to the current scene (e.g., "Player", "World/Enemies/Boss") and calls the named method with optional arguments. Returns the serialized result. The project must be running via run_interactive.

Search the live runtime scene tree by name pattern and/or type, including dynamically spawned nodes. For static .tscn analysis, use get_scene_tree. Requires run_interactive.

Execute an arbitrary GDScript expression at runtime and return the result. The expression runs in the context of the current scene (e.g., "get_tree().current_scene.name", "Vector2(1,2).length()"). Useful for debugging, querying state, and one-off calculations. The project must be running via run_int…

Capture a screenshot from a running interactive project. Slowest verification path — use only when visual appearance itself matters (rendering, layout, animation). For gameplay/logic checks prefer game_state, evaluate_expression, or get_runtime_errors: structured, and much faster than writing and re…

Send a single keyboard key event to a running interactive Godot project. Supports any key name recognized by Godot (e.g., "space", "a", "escape", "f1") and modifier keys. For sending multiple keys, prefer send_key_sequence — it processes all keys server-side in one round-trip with optional state/scr…

Send a mouse click (press+release) at specific coordinates. For cursor movement, use send_mouse_motion. For dragging, use send_mouse_drag. Requires run_interactive.

Move the mouse cursor to specific coordinates without clicking. Use for hover effects, aiming, and cursor tracking. Requires run_interactive.

Send a mouse drag (press, move, release) from one position to another. For simple clicks, use send_mouse_click. Requires run_interactive.

Block until a signal is emitted on a node in the running game. Useful for sequencing test steps (e.g., wait for "animation_finished" or "died"). Returns whether the signal was received or the wait timed out. The project must be running via run_interactive.

Block until a node appears in the scene tree. Useful for waiting on dynamically spawned nodes (e.g., wait for "Player/Sword" to appear after equip). Returns whether the node was found or the wait timed out. The project must be running via run_interactive.

Retrieve performance metrics (FPS, draw calls, memory, node count, etc.) from a running project. Optionally filter to specific metrics. Requires run_interactive.

Reload the current scene in a running interactive Godot project. Useful for resetting game state during test loops. The project must be running via run_interactive.

Retrieve runtime errors, warnings, and backtraces since the last call. Returns structured entries with error type, source, and stack traces. Requires Godot 4.5+ and run_interactive.

Analyze a scene's architecture: type distribution, signals, sub-scenes, scripts, groups, and tree depth. Runs headless (no game needed).

Analyze a GDScript file: classify methods, identify signals, map dependencies, and list exports. Takes a scriptPath, not a nodePath. Runs headless (no game needed).

Run GUT (Godot Unit Testing) tests via headless Godot. Requires GUT installed (addons/gut/). Returns pass/fail summary and console output.

Primary gameplay testing tool. Sends multiple raw keys and/or InputMap actions in one round-trip with inline checkpoints: {"wait": ms} delays, {"state": true} state snapshots, {"screenshot": "path"} captures, collectSignals for signal events. Replaces send_input/send_key loops with shell sleeps and …

Send a gamepad button event (A, B, X, Y, shoulders, dpad, start, etc.) to a running project. For input actions, prefer send_input. Requires run_interactive.

Send a gamepad analog stick or trigger axis event. Simulates analog input with float precision. For input actions, prefer send_input. Requires run_interactive.

Pause or unpause a running project. MCP receiver stays active for screenshots, state queries, and property changes while paused. Requires run_interactive.

Set a property on a live node at runtime. Changes are immediate but NOT saved to disk — use set_node_properties for permanent changes. Requires run_interactive.

Validate a GDScript file for syntax errors using Godot's parser in headless mode. No running game needed.

Execute a multi-line GDScript block at runtime in the current scene context. Unlike evaluate_expression, supports variables, loops, and control flow. Requires run_interactive.

Subscribe to signals on a node for persistent monitoring. Retrieve with get_signal_events. For single-sequence monitoring, prefer send_key_sequence with collectSignals. Requires run_interactive.

Retrieve buffered signal events from subscribe_signals. Returns signal name, arguments, and timestamp; clears buffer by default. Requires run_interactive.

Search the Godot Asset Library for addons and project templates. Returns matching assets with the asset_id you pass to install_asset. Read-only network call to the public Asset Library REST API.

Download an asset from the Godot Asset Library and extract it into a project. Provide assetId (download URL and sha256 are resolved and verified via the Asset Library) or a direct downloadUrl. The archive's single wrapping folder is stripped by default so addons land under res://addons/. Files are w…

List available tools by category. Categories: process, project, scene, node, animation, tilemap, resource, script, signal_group, uid, settings, interactive, screenshot, analysis, testing, assets, meta.