Godot MCP Runtime
Godot MCP Runtime lets AI agents edit Godot 4.x projects headlessly and drive a running game to verify changes.
Create, modify, duplicate, delete, and save scenes/nodes; set/get properties; load sprites; export MeshLibrary; batch scene operations.
Manage autoloads, attach scripts, connect/disconnect signals, and validate GDScript or scene structure/signals.
Inspect projects: list/find projects, check project/runtime status, read files/tree, search code, parse settings and scene dependencies.
Run, attach to, detach from, and stop Godot projects; capture stdout/stderr and exit status.
Control a live game: take screenshots, simulate keyboard/mouse/UI/text/action input, discover UI elements, and execute live GDScript.
Profile runtime performance with function captures, frame/FPS data, engine servers, worst frame, and start/stop profiler control.
Open the Godot editor for a human, run games in background/off-screen mode, and rely on automatic bridge cleanup.
Godot MCP Runtime
A lightweight MCP server that gives AI agents the tools to interact with the Godot game engine. Features comprehensive headless editing and full runtime control over a Godot 4.x project. Scene, node, autoload, and validation ops cover everything short of the most niche corners of the engine; the runtime bridge adds screenshots, input simulation, UI discovery, and live GDScript against the running scene tree.
Headless editing: scenes, nodes, scripts, signals, validation, no editor window
Runtime control: screenshots, input simulation, UI discovery, live GDScript, and profiling (functions, FPS, monitors, render stages) against the running game
Zero footprint: no Godot addon, no project commits, auto-cleanup on shutdown
No addon required. Most Godot MCP servers that offer runtime support ship as a Godot addon, something you install into your project, commit to version control, and manage as a dependency. Use npx and there's no install or setup needed.
Think of it as Playwright MCP, but for Godot. This does the same thing for games: run the project, take a screenshot, simulate input, read what's on screen, execute a script against the live scene tree. The agent closes the loop on its own changes rather than handing off to you to verify.
This is not a playtesting replacement. It doesn't catch the subtle feel issues that only a human notices, and it won't tell you if your game is fun. What it does is let an agent confirm that a scene loads, a button responds, a value updated, a script ran without errors. The ability to check work is crucial for AI driven workflows.
Contents
Related MCP server: Godot MCP
What It Does
This server is the perfect tool kit for AI assisted game development with Godot. It provides a comprehensive suite of tools that allows agents to create scenes, nodes, scripts, and more. The runtime tool set provides the capabilities to check work by running the game and interacting with it in real time, all without becoming a cumbersome dependency on your project.
Built for agents. Every tool is purpose-built and self-documenting. When something fails, the response tells the agent how to fix it; when something succeeds, it points toward the next step. The result is an AI that stays unstuck and self-corrects without needing you to nudge it along. All 43 tools return one JSON object with a declared output schema, and a value the server could not measure comes back as null with a warning rather than a made-up number.
Headless editing. Create scenes, add nodes, set properties, attach scripts, connect signals, validate GDScript. All the standard operations, no editor window required.
Runtime bridge. When run_project is called, the server injects McpBridge as an autoload. This opens a localhost-only TCP listener (a free port is auto-selected when bridgePort is omitted; pass bridgePort to pin a specific port) and enables:
Screenshots: Capture the viewport. By default this returns a 960x540 preview inline plus the full PNG on disk, and every call also returns pixel statistics (
stats, with alikelyBlankverdict) measured from the full PNG, so a caller that cannot look at the image can still tell a rendered frame from a blank oneInput simulation: Batched sequences of key presses, mouse clicks, mouse motion, UI element clicks by name or path, Godot action events, text typed into the focused Control, and timed waits. Each action reports what it did: the Control it hit, the signals it fired, and what changed on screen
UI discovery: Walk the live scene tree and collect every visible Control node with its position, type, text content, and disabled state
Live script execution: Compile and run arbitrary GDScript with full SceneTree access while the game is running
Profiling: With
profiling: trueat launch, capture Godot's own profiler and rank the most expensive GDScript functions by own or inclusive time, with source locations and per-frame averages. Every capture also reports FPS, frames over a target frame rate, and engine monitors (draw calls, memory, node counts);visual: trueadds the Visual Profiler's CPU and GPU time per render stage, andtimeline: truethe same over time, with the player position (track) on each interval, to find where a walk through the level drops frames
Background mode. Pass background: true to run_project and the Godot window is never shown on Windows; on other platforms it is moved off-screen (positioned at (-9999, -9999)) after startup. Mouse input passes through the window. It does not guarantee the game never takes keyboard focus. Programmatic input, screenshots, and all runtime tools work exactly the same. Useful for automated agent-driven testing where the window shouldn't be visible or interactive.
Manual attach mode. When something other than MCP launches the game (a CI pipeline, an external debugger, your own shell), call run_project with attach: true first. It injects the bridge and marks the project active without spawning Godot, so when you launch the game manually, runtime tools work against it. Call stop_project when done: it removes the bridge and leaves your Godot process running.
Render check. render_movie renders a fixed number of frames in a separate short Godot run under the engine's movie writer and reports what rendered: blank or not, moving or not. It injects no bridge, simulates no input and starts no session, so it works as a cheap checkpoint before a full run_project. 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.
Several projects at once. run_project on a second project adds a session instead of ending the first, which helps when a game and a small repro project run side by side. The runtime tools act on the current session and name it in every response as projectPath; switch_project moves them to another one. Nothing falls back silently: if the current session ends, the next call errors and lists the sessions still live. The server runs one runtime operation at a time, so calls issued in parallel wait their turn instead of interleaving.
get_debug_output has nothing to return in attached mode. stdout and stderr only flow through processes MCP started itself, so for an externally launched Godot its output, errors and running are null with a warning, never empty lists. Let run_project spawn the game if you need the debug stream.
The bridge cleans itself up automatically - on stop_project, and also without a tool call when the game exits on its own, the bridge connection drops, or the server shuts down (including a client that just closes the connection). A game the server spawned also quits by itself within a few seconds if the server process is killed outright, and removes the autoload entry from project.godot on its way out. Its artifacts live under .mcp/godot-runtime/ in the project, which the server adds to .gitignore. No leftover autoloads, no modified project files.
How It Compares
The Godot MCP space splits on two axes: whether a server can drive a running game (runtime) or only edit files, and what it costs your project to do so. Most servers that offer real runtime control ship as a Godot addon you install and commit to version control, or as a custom engine you download. This one injects a bridge transiently and removes it on shutdown, so you get full live-game control against stock Godot with nothing left in your repo.
Server | Live-game runtime | Footprint | License | Price |
Godot MCP Runtime | Full: screenshots, input, live scene tree, script exec | Zero ( | MIT | Free |
Summer Engine | Full | Custom engine download + sign-in | MIT layer / proprietary engine | Free core, paid cloud |
tugcantopaloglu/godot-mcp | Full | Committed autoload addon | MIT | Free |
Godot MCP Pro | Full | Committed editor addon | Proprietary | $15 |
GDAI MCP | Editor-mediated | Committed editor addon | Proprietary | $19 |
Coding-Solo/godot-mcp | No (launch + debug output) | Zero ( | MIT | Free |
Among servers with full live-game control, Godot MCP Runtime pairs a zero-footprint install (no addon committed to version control, no custom engine, no account) with a single npx command, and it has shipped this transient-autoload runtime bridge since February 2026. For the full field of ~20 servers with a source for every claim, see docs/comparison.md.
Quick Start
Prerequisites
That's it. No Godot addon, no project modifications.
Configure Your MCP Client
Add the following to your MCP client config. Works with Claude Code, Claude Desktop, Cursor, or any MCP-compatible client.
Ask your AI assistant to call check_project. If it returns a Godot version string (e.g., 4.5.stable), you're connected and working.
Zero-install via npx (recommended):
{
"mcpServers": {
"godot": {
"command": "npx",
"args": ["-y", "godot-mcp-runtime"],
"env": {
"GODOT_PATH": "<path-to-godot-executable>"
}
}
}
}Or install globally:
npm install -g godot-mcp-runtime{
"mcpServers": {
"godot": {
"command": "godot-mcp-runtime",
"env": {
"GODOT_PATH": "<path-to-godot-executable>"
}
}
}
}Or clone from source:
git clone https://github.com/Erodenn/godot-mcp-runtime.git
cd godot-mcp-runtime
npm install
npm run build{
"mcpServers": {
"godot": {
"command": "node",
"args": ["<path-to>/godot-mcp-runtime/dist/index.js"],
"env": {
"GODOT_PATH": "<path-to-godot-executable>"
}
}
}
}Prefer pnpm? All three install paths work with pnpm. Substitute pnpm dlx godot-mcp-runtime for npx -y godot-mcp-runtime, pnpm add -g godot-mcp-runtime for the global install, or pnpm install && pnpm run build for the source build. pnpm ships stronger defaults against npm supply-chain attacks; see pnpm's supply chain security guide.
If Godot is on your PATH, you can omit GODOT_PATH entirely. The server will auto-detect it.
Optional environment variables
All are set in the same env block as GODOT_PATH:
Variable | Effect |
|
|
GODOT_MCP_DISABLE_ELICITATION-"true"skips the confirmation prompts for the firstrun_projectlaunch,render_movieandrun_scripton a project. Use this if your client cannot display elicitation prompts (e.g. Claude Desktop, which auto-cancels them). The action proceeds with a warning.
{
"mcpServers": {
"godot": {
"command": "npx",
"args": ["-y", "godot-mcp-runtime"],
"env": {
"GODOT_PATH": "<path-to-godot-executable>",
"GODOT_MCP_DISABLE_ELICITATION": "true"
}
}
}
}Windows path gotchas. GODOT_PATH must point at the Godot executable itself, not its install folder. Backslashes in JSON must be escaped or replaced with forward slashes:
"GODOT_PATH": "D:\\Godot\\Godot_v4.5-stable_win64.exe"
// or equivalently
"GODOT_PATH": "D:/Godot/Godot_v4.5-stable_win64.exe"Setting the variable from a wrapper .bat does not propagate to the MCP server - the path must live in the client's env block above.
Security
The server does not sandbox anything. A launched project and run_script run with your user permissions, and the server asks you to confirm once per project per session before the first of each. SECURITY.md lists what runs code, what the agent can change and how to report a vulnerability.
Docs
docs/tools.md: full tool reference, grouped by categorydocs/tool-authoring.md: standards for adding or modifying toolsdocs/architecture.md: source layout, bridge sequence diagram, lifecycle steps, runtime artifact behaviorSECURITY.md: trust model, what runs code, what the confirmation prompts cover, how to report a vulnerabilitydocs/migration-4.0.md: every breaking change from 3.8.1 to 4.0, with its before and after
Acknowledgments
Built on the foundation laid by Coding-Solo/godot-mcp for headless Godot operations.
Developed with Claude Code.
License
Available Tools
43 toolsadd_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).
Inputs: projectPath (required), autoloadName (required), autoloadPath (required), singleton. Returns: tip, autoload, warnings
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.
Inputs: nodeName (required), nodeType (required), scenePath (required), projectPath (required), +7 more. Returns: nodeName, nodePath, nodeType, warnings
attach_scriptAIdempotent
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.
Inputs: nodePath (required), scenePath (required), scriptPath (required), projectPath (required). Returns: nodePath, warnings, scriptPath
batch_scene_operationsADestructive
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.
Inputs: operations (required), projectPath (required), abortOnError. Returns: results, warnings
check_projectARead-only
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.
Inputs: projectPath. Returns: name, runtime, warnings, structure, +2 more
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.
Inputs: method (required), signal (required), nodePath (required), scenePath (required), +2 more. Returns: method, signal, nodePath, warnings, +2 more
create_resourceADestructive
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.
Inputs: type (required), projectPath (required), resourcePath (required), overwrite, +1 more. Returns: warnings, properties, scriptPath, resourcePath, +1 more
create_sceneAIdempotent
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.
Inputs: scenePath (required), projectPath (required), rootNodeType. Returns: warnings, scenePath
delete_nodesADestructive
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.
Inputs: nodePaths (required), scenePath (required), projectPath (required). Returns: results, warnings
disconnect_signalADestructive
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.
Inputs: method (required), signal (required), nodePath (required), scenePath (required), +2 more. Returns: method, signal, nodePath, warnings, +2 more
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.
Inputs: nodePath (required), scenePath (required), projectPath (required), newName, +2 more. Returns: nodePath, warnings, newNodePath
export_mesh_libraryADestructive
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.
Inputs: scenePath (required), outputPath (required), projectPath (required), meshItemNames. Returns: warnings, itemCount, itemNames, outputPath
get_debug_outputARead-only
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 limit lines each, default 200), running (false after exit) and exitCode after exit. An attached session captures nothing: output, errors and running are null and warnings leads.
Inputs: limit. Returns: tip, errors, output, running, +4 more
get_node_propertiesARead-only
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.
Inputs: nodes (required), scenePath (required), projectPath (required). Returns: results, warnings
get_node_signalsARead-only
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.
Inputs: nodePath (required), scenePath (required), projectPath (required). Returns: signals, nodePath, nodeType
get_project_filesARead-only
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.
Inputs: projectPath (required), maxDepth, subfolder, extensions. Returns: name, path, type, children, +2 more
get_project_settingsARead-only
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.
Inputs: projectPath (required), section. Returns: section, settings, warnings
get_scene_dependenciesARead-only
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.
Inputs: scenePath (required), projectPath (required). Returns: warnings, scenePath, dependencies
get_scene_treeARead-only
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.
Inputs: scenePath (required), projectPath (required), maxDepth, parentPath. Returns: name, path, type, script, +3 more
get_ui_elementsARead-only
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.
Inputs: root, filter, visibleOnly. Returns: tip, elements, warnings, projectPath
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.
Inputs: projectPath (required). Returns: pid, message, projectPath
list_autoloadsARead-only
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.
Inputs: projectPath (required). Returns: warnings, autoloads
list_projectsARead-only
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.
Inputs: directory (required), recursive. Returns: projects, warnings
load_spriteAIdempotent
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.
Inputs: nodePath (required), scenePath (required), projectPath (required), texturePath (required). Returns: nodePath, nodeType, warnings, texturePath
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.
Inputs: moves (required), scenePath (required), projectPath (required). Returns: results, warnings
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 seconds (default 5, max 30; longer: start_profiler). Times are elapsed, not CPU; never sum totalMs (rows overlap). Returns: warnings first, projectPath, complete, fps, slowFrames, rows, frame, servers, worstFrame, monitors, visual, timeline. Errors if profiling is off, a capture is open or the game exits mid-window.
Inputs: top, sort, track, visual, +7 more. Returns: fps, rows, sort, frame, +21 more
remove_autoloadADestructive
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.
Inputs: projectPath (required), autoloadName (required). Returns: removed, autoloads
render_movieADestructive
Render frames frames of the project (or scene) in a separate movie-writer run: no bridge, session or input (to interact: run_project, simulate_input). mode check (default): stats, likelyBlank, motion, inline frames, files deleted. frames: keeps PNGs. video: .avi/.ogv, no stats. Returns: frameCount, likelyBlank, anyMotion, samples, paths, bytesWritten; warnings leads if unmeasured or unconfirmed. Needs a display; asks the user once per project. Errors on timeout, failed run or live session.
Inputs: projectPath (required), fps, mode, scene, +3 more. Returns: fps, mode, path, scene, +21 more
run_projectADestructive
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.
Inputs: projectPath (required), scene, attach, profiling, +2 more. Returns: message, warnings, bridgePort, projectPath, +1 more
run_scriptADestructive
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.
Inputs: script (required), timeout. Returns: tip, result, warnings, projectPath
save_sceneAIdempotent
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.
Inputs: scenePath (required), projectPath (required), newPath. Returns: warnings, scenePath, savedScenePath
search_projectARead-only
Plain-text (substring, not regex) search across project files; the text goes in pattern. Default fileTypes ["gd","tscn","cs","gdshader"]; caseSensitive false; maxResults integer >= 1, default 100. Skips hidden entries and .mcp. Returns: matches[] (project-relative file, 1-indexed lineNumber, line), truncated, filesSearched, fileTypes. warnings leads when no file had a searched extension or a path was unreadable. Errors if pattern holds a line break or a parameter is undeclared.
Inputs: pattern (required), projectPath (required), fileTypes, maxResults, +1 more. Returns: matches, warnings, fileTypes, truncated, +1 more
set_node_propertiesAIdempotent
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.
Inputs: updates (required), scenePath (required), projectPath (required), abortOnError. Returns: results, warnings
set_project_settingAIdempotent
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? }.
Inputs: key (required), section (required), projectPath (required), value, +1 more. Returns: key, value, created, section, +3 more
set_resource_propertiesAIdempotent
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.
Inputs: properties (required), projectPath (required), resourcePath (required). Returns: warnings, properties, scriptPath, resourcePath, +1 more
simulate_inputADestructive
Send input actions. key, mouse_button, action: omit pressed to tap; set it to hold or release. click_element takes a node path or name (see get_ui_elements), not text, and scrolls its target into view. Returns: projectPath, success, results[]: ok, hit, scrolled, signals, changes, watch, mouse_motion position (as delivered), errors (spawned only); warnings leads if errors is partial. An invalid batch injects nothing; a failure skips the rest. A covered or clipped click is refused.
Inputs: actions (required), watch. Returns: results, success, warnings, still_held, +1 more
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 seconds (default 30, max 60); read it with stop_profiler. Unattended window: use profile_project. Returns: warnings if any, projectPath, active, visual, timeline, timelineMs, firstFrame, captureLimit, maxSeconds. Errors if a capture is running or profiling was off.
Inputs: track, visual, seconds, timeline, +5 more. Returns: active, visual, timeline, warnings, +5 more
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.
Inputs: top, sort. Returns: fps, rows, sort, frame, +21 more
stop_projectADestructive
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.
Inputs: no named parameters. Returns: pid, message, exitCode, warnings, +7 more
switch_projectAIdempotent
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.
Inputs: projectPath (required). Returns: live, message, exitCode, warnings, +5 more
take_screenshotARead-only
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.
Inputs: timeout, responseMode, previewMaxWidth, previewMaxHeight. Returns: path, size, stats, warnings, +4 more
update_autoloadAIdempotent
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.
Inputs: projectPath (required), autoloadName (required), singleton, autoloadPath. Returns: autoload, warnings
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.
Inputs: projectPath (required), checks, source, targets, +2 more. Returns: valid, errors, results, warnings
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
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.
Maintenance
Related MCP Connectors
Make games with AI: one MCP server that connects your agent to Unity, Unreal and Godot editors.
A TypeScript MCP server for Home Assistant, enabling programmatic management of entities, automati…
An MCP server that gives your AI access to the source code and docs of all public github repos
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to control Unreal E…
Related MCP Servers
- AlicenseBqualityDmaintenanceA Model Context Protocol server that enables AI assistants to interact with the Godot game engine, allowing them to launch the editor, run projects, capture debug output, and control project execution.146,695MIT
- AlicenseNot gradedqualityDmaintenanceProvides a comprehensive integration between LLMs and the Godot Engine, enabling AI assistants to intelligently manipulate project files, scripts, and the live editor. It supports advanced workflows including version-aware documentation querying, automated E2E game testing, and real-time visual context capture.26MIT
- AlicenseNot gradedqualityCmaintenanceA local MCP server plus a bundled Godot editor addon that lets an AI agent create, inspect, run, debug, and export real Godot 4.6 games through tools.2PolyForm Small Business 1.0.0
- AlicenseNot gradedqualityBmaintenanceA TypeScript MCP server bridging MCP clients to Godot 4 editor, enabling scene, node, script editing and more via WebSocket.187 npmMIT