Godot MCP Runtime
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| DEBUG | No | Set to "true" for verbose logging. | |
| GODOT_PATH | No | The path to the Godot executable. If Godot is already on your system PATH, you can omit this entirely as the server will auto-detect it. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Godot MCP Server - AI-driven Godot 4.5+ project manipulation.
Tool categories:
Project management: launch_editor, run_project, switch_project, stop_project, get_debug_output, list_projects, check_project
Scene editing (headless): create_scene, add_node, load_sprite, save_scene, export_mesh_library, batch_scene_operations
Node editing (headless): delete_nodes, set_node_properties, get_node_properties, attach_script, get_scene_tree, duplicate_node, move_nodes, get_node_signals, connect_signal, disconnect_signal
Resource files (headless): create_resource, set_resource_properties
Runtime (requires run_project): take_screenshot, simulate_input, get_ui_elements, run_script
Render check (no runtime session): render_movie
Profiling (requires run_project with profiling: true): profile_project, start_profiler, stop_profiler
Project config (no Godot process): list_autoloads, add_autoload, remove_autoload, update_autoload, get_project_files, search_project, get_scene_dependencies, get_project_settings, set_project_setting
Validation: validate
Key behaviors:
All mutation operations (add_node, set_node_properties, delete_nodes, etc.) save the scene automatically. Only use save_scene for save-as (newPath) or re-canonicalization.
Headless Godot loads every registered autoload. An autoload that stops the engine before the operation is dispatched (for example one that quits in _init) fails every headless operation; one that only errors in _ready does not. Check the script with validate, and use list_autoloads / remove_autoload to find and remove it.
run_project waits for the MCP bridge before returning success and returns a JSON payload (sessionMode, bridgePort, warnings). If the bridge never answers it returns an error and tears the session down; retry run_project.
run_project with attach: true is the path for a Godot process you launch yourself: it injects the bridge and marks the project active, but spawns nothing and captures no stdout/stderr. It asks no launch confirmation; run_script still asks once per project. stop_project ends it without killing that process.
Several projects can run at once, one session per project. run_project on another project adds a session and makes it current; it does not stop the others. The runtime tools, the profiling tools, get_debug_output and stop_project act on the current session only, and every response names it in projectPath. switch_project({ projectPath }) changes which session is current. stop_project stops the current session and leaves none current. When no session is current, or the current one's game has exited, these tools return an error listing the live sessions instead of picking one: call switch_project. check_project reports the current project and every live session.
A runtime session runs one operation at a time. A runtime, profiling or session call issued while another is still running waits for it (up to 30 s) and then returns an error naming the operation it waited behind; nothing was sent for it, so retry once that operation has returned.
A runtime session ends by itself when the game exits or an attached bridge disconnects: the bridge autoload is removed at that moment and the scene-editing tools unblock. After a spawned game exits, stop_project is still worth calling (it frees the retained process slot and returns the captured logs) and succeeds. After an attached session ends by itself nothing is left to stop: stop_project then reports no active session, which needs no follow-up.
click_element in simulate_input resolves by node path or node name (BFS search), NOT by visible text. Use get_ui_elements to discover valid element identifiers.
simulate_input reports per-action results (signals fired, the Control hit, UI changes, watched values), so it needs no take_screenshot round trip to tell whether an action landed. Omitting
pressedtaps; set it only to hold or release across actions.render_movie is a separate short Godot run under the movie writer, with no bridge and no input: use it to check that a scene renders (likelyBlank) or animates (anyMotion) without starting a session. It needs a display, asks for the same launch confirmation as run_project, and is refused while a runtime session is live on the same project.
run_script expects GDScript with "extends RefCounted" and "func execute(scene_tree: SceneTree) -> Variant".
run_project spawns Godot without -d so runtime errors do not pause execution; the
breakpointkeyword in user code is a no-op (no debugger is attached). SCRIPT ERROR output and GDScript backtraces still appear in stderr.profiling: true attaches Godot's own remote debugger for the profiling tools. Errors and
breakpointstill do not pause the game - the server answers every debugger break with continue.Every capture reports fps and engine monitors (draw calls, memory, node counts); pass visual: true to profile_project or start_profiler for CPU/GPU time per render stage, and timeline: true (with track: ["/root/Main/Player:global_position"]) to see when and where frames got slow. To capture while simulate_input walks the game, call start_profiler, then simulate_input, then stop_profiler: profile_project holds the session for its whole window, so no other runtime call runs inside it.
Confirmation prompts: the first run_project (spawn mode) or render_movie on a project in a server session asks the user to confirm, because the project's code runs with the user's permissions. The first run_script on a project asks too, because agent-written GDScript runs with those permissions; a launch confirmation does not cover it, and an attached session asks as well. Each prompt is asked once per project per server session, and nothing is scanned. If the user declines, do not call the tool again on that project unless they ask. GODOT_MCP_DISABLE_ELICITATION=true skips the prompts for clients that cannot display them. See SECURITY.md.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| launch_editorA | Open the Godot editor GUI for a project, for the human user. Use only when the user asks to open the editor; for agent-driven work use the headless scene and node tools (add_node, set_node_properties, etc.), since the editor cannot be controlled programmatically. Returns: projectPath, the editor process pid and message. Errors if projectPath has no project.godot or the editor process does not start. |
| run_projectA | Start a runtime session: spawn the project (stdout/stderr captured; asks the user to confirm the first time per project), or with attach: true wait for a Godot you launch yourself (nothing spawned or captured). Required before take_screenshot, simulate_input, get_ui_elements and run_script; returns once the bridge answers. It becomes current; others keep running. Returns: projectPath, sessionMode, bridgePort, message; warnings leads on a start caveat. Errors if the bridge never answers. |
| switch_projectA | Point the runtime tools (screenshots, input, UI, run_script, debug output, profiling, stop_project) at another project's session. Needed only when several sessions exist; run_project makes its own session current. A session whose game exited can be selected to read its logs or stop it: live is then false and warnings leads. Returns: projectPath, previousProjectPath, live, sessionMode, bridgePort, bridgeResponsive, message. Errors if the project has no session, listing the live ones. |
| get_debug_outputA | Read captured stdout/stderr from a spawned Godot project. Use whenever a runtime tool fails unexpectedly: script errors, missing nodes and crash backtraces surface here. Still works after the process exits or crashes; the logs are kept until stop_project. Returns: projectPath, sessionMode, output and errors (last |
| stop_projectA | End the current session now and remove the bridge, cutting off a runtime call in progress. A spawned Godot is stopped; an attached one is detached, not killed. Other sessions keep running; none becomes current. Also frees a spawned game that exited by itself (alreadyExited). Returns: projectPath, message, sessionMode, externalProcessPreserved, alreadyExited, exitCode, killUnconfirmed, finalOutput, finalErrors; warnings leads if the kill or cleanup was unconfirmed. Errors if nothing is running. |
| take_screenshotA | Save a PNG of the running viewport under .mcp/godot-runtime/screenshots/ (kept after stop_project). responseMode: preview (default; inline, fits default 960x540, max 1920x1080), full (inline PNG, for small text), path_only (no image). Returns: projectPath, path, size, stats {chromatic, dominant, distinct, likelyBlank} from the full PNG, so a blank frame shows without vision. warnings leads if stats is null or the image is too big to inline. Errors: no session, no frame rendered, bridge timeout. |
| simulate_inputA | Send input actions. key, mouse_button, action: omit |
| get_ui_elementsA | List the running scene Controls with rect, type and text. Call before simulate_input click_element to find names and paths. Needs a runtime session. visibleOnly (default true) drops hidden Controls and ones clipped out of view. filter narrows by class; root limits the list to one Control and its descendants. Returns: projectPath, elements[] with path/type/rect/visible/onScreen (visibleRect if clipped), optional text/disabled/tooltip. Errors on a non-Control filter or an unknown root. |
| run_scriptA | Run GDScript in the running game. It must extend RefCounted and define func execute(scene_tree: SceneTree) -> Variant; execute may await, cut off at the timeout (not cancelled). Return is JSON-serialized: vectors as {x,y[,z,w]}, Color as {r,g,b,a}, a Node as {class,name,path}. Compiled with project warnings. Returns: projectPath, result, warnings, tip. Spawned: a runtime error is an error if result is null, else a warning. Attached: errors are unobservable. Asks the user once per project. |
| render_movieA | Render |
| list_autoloadsA | List the autoloads registered in a project, with their paths and singleton flags. Use first when diagnosing headless failures: an autoload that stops the engine before an operation is dispatched fails every headless operation. Reads project.godot directly, no Godot process. Returns: autoloads[], each { name, path, singleton }, one per name (the last assignment, which the engine keeps); empty when none. warnings leads when a line is not listed or is not in the form Godot writes. |
| add_autoloadA | Register a new autoload. autoloadPath takes res://... or a project path. singleton defaults to true. No Godot process is used. An autoload that stops the engine before a headless operation is dispatched fails all of them: run validate on it first. Returns: autoload { name, path, singleton } read back from project.godot, and a tip. Errors if the name exists (use update_autoload), or a singleton shares its name with a class_name a project script declares (the engine then drops the script). |
| remove_autoloadA | Unregister an autoload from a project by name. Use to recover from an autoload that stops the engine before headless operations are dispatched. No Godot process is used. Returns: removed (the name) and autoloads[], the entries that remain, read back from project.godot. Errors if no autoload has that name. |
| update_autoloadA | Change an existing autoload's path or singleton flag. Pass autoloadPath, singleton or both; errors if neither is given. An omitted field keeps its current value. Use instead of remove_autoload plus add_autoload: one edit, no window where the autoload is missing. No Godot process is used. Returns: autoload { name, path, singleton } read back from project.godot. Errors if autoloadName is not registered, or if the result is a singleton named like a class_name a project script declares. |
| list_projectsA | Find Godot projects under a directory by locating project.godot files. Use when no project is named; to inspect a known one use check_project. recursive: true descends into subdirectories (skipping .git, .godot, node_modules, etc.); the default checks the directory and its immediate children. Returns: projects[], each { projectPath, name }, name being config/name else the folder name. warnings leads when a path could not be read or a link was not followed. Errors if directory is not a directory. |
| check_projectA | Get project metadata and the Godot version, plus a runtime block. runtime.activeSession, sessionMode and bridgeResponsive describe the current session, projectPath its project (null when none), liveSessions all live ones. With projectPath, runtime.project is that project's session: live, exited or none. Returns: { name?, projectPath?, structure?, godotVersion, runtime }; warnings leads if structure is partial or the engine is newer than the project. Errors if projectPath lacks project.godot. |
| get_project_filesA | Return the file tree of a Godot project. Use to discover project structure when paths are unknown. subfolder lists one folder as the root (maxDepth counts from it). extensions filters files (e.g. ["gd","tscn"]) and drops directories with no match; maxDepth -1 is unlimited. Skips dot-prefixed entries. Returns: the root node { name, type, path, children[] }; a child is a file, a directory, or a link (not followed). A directory not opened or unreadable has children null; warnings leads then. |
| search_projectA | Plain-text (substring, not regex) search across project files; the text goes in |
| get_scene_dependenciesA | Parse a .tscn file for ext_resource references (scripts, textures, subscenes). Use to see what a scene depends on before refactoring or moving files. Returns: scenePath and dependencies[], one per ext_resource reference (path, type, optional uid). warnings leads when ext_resource lines could not be read. Errors if the file does not exist or is not a text scene or resource. |
| get_project_settingsA | Parse project.godot into JSON without launching Godot. Use to inspect display, input and rendering settings. Pass section for one INI section. Returns: settings as { [section]: { [key]: value } }, or { [key]: value } plus section. Strings are unescaped, an empty value is null, complex values stay raw text. Keys before any section are under global. warnings leads when the section is absent, a value is unterminated or empty, a line is not as Godot writes it, or a setting is assigned twice. |
| set_project_settingA | Set one project.godot setting without launching Godot. Pass value (JSON, converted to a Godot literal) or literal (raw Godot text, e.g. "Vector2i(1280, 720)"), not both. Rewrites the last assignment in place or adds key/section; other lines stay byte for byte. Refuses autoload/* (use the autoload tools). Returns: { section, key, value read back, created, sectionCreated, previous? }. |
| create_sceneA | Create a new scene file with a single root node, written to scenePath. Use to start a scene from scratch; to add nodes to an existing scene use add_node. rootNodeType defaults to Node2D: pass "Node3D" for 3D or "Control" for UI. Saves automatically and overwrites an existing file silently. Returns: the scenePath that was written. Errors while a runtime session is live on this project. |
| add_nodeA | Add a node to a scene, or instance another scene when nodeType is a scene path. Saves automatically. Values in properties are checked against each property's declared type; a mismatch errors (Property Values in docs/tools.md). Returns: nodeName, nodeType and nodePath, read back after the add; warnings leads when Godot renamed the node or a value will not be saved. Errors and adds nothing if the type, parent or a property is invalid. Errors while a runtime session is live on this project. |
| load_spriteA | Set the texture on an existing Sprite2D, Sprite3D or TextureRect. For a new node, pass texture in add_node properties instead. Saves automatically. texturePath must be a file under projectPath. Returns: nodePath, nodeType and texturePath, read back from the node after the assignment. Errors if the node is not one of those three classes or the texture file does not exist. Errors while a runtime session is live on this project. |
| save_sceneA | Re-pack and save a scene, optionally to another path (save-as). The mutation tools save by themselves: use this only for save-as via newPath, or to re-canonicalize a hand-edited .tscn. Overwrites silently. A newPath file gets no uid of its own. Returns: scenePath (loaded) and savedScenePath (written, confirmed on disk); warnings leads if the save dropped content. Errors while a runtime session is live on this project. |
| export_mesh_libraryA | Export a scene's MeshInstance3D children as a MeshLibrary for GridMap. The outputPath extension sets the format: .tres is text (prefer it: readable, diffable), .res is binary. Not for 2D scenes. meshItemNames picks a subset, else all. Overwrites silently. Returns: outputPath, itemCount, itemNames read from the saved library; warnings leads when a requested name was not exported. Errors if no valid meshes, or while a runtime session is live. |
| batch_scene_operationsA | Run several scene mutations in one process; every mutated scene is saved at the end. Use instead of chaining add_node, load_sprite, set_node_properties or save_scene. Each item sets operation (save stands for save_scene) and takes that tool's params. abortOnError stops at the first failure; later items return skipped: true. Returns: results[] in input order: operation, scenePath, success, error or skipped, plus the operation's own fields. Errors while a runtime session is live on this project. |
| create_resourceA | Create a .tres resource file from an engine Resource class or a GDScript resource script (class_name or path), with property values set. Values are checked against declared types as in set_node_properties (Property Values in docs/tools.md). Refuses an existing file unless overwrite is true. Returns: resourcePath, resourceType, scriptPath and properties read back from the saved file. Errors on an unknown type or property, and while a runtime session is live on this project. |
| set_resource_propertiesA | Set property values in an existing .tres resource file and save it. Properties not named, sub-resources and uids stay as the file has them. A Dictionary or Array value replaces the stored one whole; send every key. Values are checked against declared types as in set_node_properties (Property Values in docs/tools.md); one invalid name or value errors and writes nothing. Returns: resourcePath, resourceType, scriptPath, the named properties read back. Errors while a runtime session is live. |
| delete_nodesA | Remove one or more nodes, with their descendants, from a scene. Always-array: pass a single-element nodePaths array for a one-off delete. Saves once at the end. The scene root, a node inside an instanced scene, and a node inherited from a base scene cannot be deleted: that entry reports an error and the rest still process. Returns: results[], one entry per nodePath in input order, each with success or error. Errors while a runtime session is live on this project. |
| set_node_propertiesA | Set node properties in a scene in one Godot process. Always-array: one update for a one-off edit. Each value is checked against the property's declared type, never stored as a zero (Property Values in docs/tools.md). A Dictionary or Array value replaces the stored one whole; send every key. Saves once. Returns: results[], one per update in input order, each with success, error or skipped; warnings leads when a value is set but not saved. Errors while a runtime session is live. |
| get_node_propertiesA | Read the current property values of one or more nodes from a scene file, in one Godot process. Always-array: pass a one-element nodes array for one node. Per-node changedOnly: true leaves out properties that match the class defaults. Returns: results[] in input order: { nodePath, nodeType, properties }, or { nodePath, error } when not found. Values use the input shapes of set_node_properties. warnings leads when changedOnly had no defaults to compare. Errors if the scene cannot be loaded. |
| attach_scriptA | Attach a GDScript or C# script to a node in a scene, replacing any script it had. Check the script with the validate tool first. C# needs the Godot .NET build with the class compiled into the project assembly. Saves automatically. Returns: nodePath and scriptPath. Errors if the script cannot be instantiated (parse errors, @abstract, or an unbuilt C# class), or if scriptPath or nodePath does not exist. Errors while a runtime session is live on this project. |
| get_scene_treeA | Get a scene's node hierarchy as a nested tree. maxDepth: 1 lists only direct children; the default -1 is the whole tree. parentPath scopes to one subtree. Returns: the root node { name, type, path, script, children[] }, every child the same shape; path is a root/... node path the node tools accept, script a res:// path or an empty string. A node cut by maxDepth has children null and a childCount, and warnings leads. Errors if the scene or parentPath is not found. |
| duplicate_nodeA | Duplicate a node and its descendants, instead of rebuilding it with add_node. newName defaults to the original name plus "2"; targetParentPath to the parent of the original. Keeps the saved signal connections like the editor; copySignals false drops them. Saves automatically. Returns: nodePath (copied node), newNodePath (read back). Errors if nodePath or targetParentPath is not found, nodePath is the root, or a runtime session is live. |
| move_nodesA | Move nodes to another parent and/or child position in a scene, each subtree kept whole (owners, groups, connections). Always-array moves, applied in order. Saves once at the end. Returns: results[] per move with success, newNodePath and index read back, or error; warnings leads when a NodePath value no longer leads where it did. Refused per entry: the root, a node inside an instance or inherited, a target inside the node, a name taken at the target. Errors while a runtime session is live. |
| get_node_signalsA | List all signals defined on a node and their current connections. Use before connect_signal/disconnect_signal to verify signal/method names. The connections[].target field is already scene-root-relative in the "root/..." form connect_signal/disconnect_signal accept as targetNodePath (a self-connection reports as "root") - pass it straight through with no conversion. Returns: nodeType and signals[], each with name and current connections (signal/target/method). Errors if node not found. |
| connect_signalA | Connect a signal on a source node to a method on a target node and persist it in the .tscn. Use get_node_signals first to confirm the names. Saves automatically. Returns: nodePath, signal, targetNodePath, method and connected, which is read back from the saved scene (null with a leading warning if that read failed). Errors if the signal or method does not exist or the connection already exists. Errors while a runtime session is live on this project. |
| disconnect_signalA | Remove a signal connection between two nodes and persist the change in the .tscn. Use get_node_signals first to confirm the connection exists; connect_signal puts it back. Saves automatically. Returns: nodePath, signal, targetNodePath, method and connected, read back from the saved scene: false once the connection is gone, null with a leading warning if that read failed. Errors if the connection does not exist. Errors while a runtime session is live on this project. |
| profile_projectA | Profile a window: GDScript function costs, fps, monitors; visual adds CPU/GPU ms per render stage, timeline both over time. Requires run_project with profiling: true. Blocks for |
| start_profilerA | Start a profiler capture and return at once, so simulate_input, run_script and screenshots drive the game while it records; timeline and track show where frames drop. Requires run_project with profiling: true. Stops itself after |
| stop_profilerA | Stop the start_profiler capture of the current session and rank what it recorded; one that hit its time limit is read back as-is, re-readable with another sort. Times are elapsed, not CPU; inclusive rows overlap, never sum totalMs. Returns: the profile_project payload: warnings first, projectPath, complete (false if cut short), fps, slowFrames, rows, frame, servers, worstFrame, monitors, plus visual and timeline when started with them. Errors if no capture was started. |
| validateA | Validate GDScript syntax or scene integrity in headless Godot. Use before attach_script or run_script. Give exactly one of scriptPath, source or scenePath, or a targets array (one process); an unknown key is an error. checks needs scenePath and instantiates the scene, running each attached script's _init(). Returns: { warnings?, valid, errors } for one target, { warnings?, results: [{ target, valid, errors }] } for targets; an invalid result always has an error. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 43 tools
Most tools have clearly scoped resource-and-action boundaries, and descriptions explicitly route ambiguous pairs such as profile_project versus start_profiler/stop_profiler, launch_editor versus run_project, save_scene versus auto-save, and batch_scene_operations versus single mutations. Still, with 43 tools there are several near-overlaps (load_sprite/set_node_properties, create_scene/add_node, get_project_settings/check_project) that require reading descriptions to choose correctly.
All tool names use snake_case and almost all are verb-first (get_, set_, add_, remove_, create_, run_, stop_), giving a predictable pattern. Minor deviations such as validate (single verb) and batch_scene_operations (noun-heavy phrasing) are small and still readable.
43 tools is well above the 25-tool threshold and forces agents to choose from many edge-case operations; the scope is broad but still feels over-fragmented across runtime, profiling, scene editing, resources, autoloads, and project settings. Some specialized tools like export_mesh_library, render_movie, duplicate_node, and move_nodes earn their place only in narrow workflows.
Coverage is broad: project discovery/settings, autoload CRUD, scene/node lifecycle and signals, scripts/validation, runtime sessions, screenshots/input/UI, profiling, and movie rendering. Minor gaps remain around file-level deletion/rename and resource read/delete (create_resource and set_resource_properties exist without matching get/delete), but core workflows are covered.