Beckett — MCP for Godot
Beckett is an MCP server embedded in the Godot editor that lets AI agents inspect, author, run, and observe Godot games over HTTP — with no sidecar process.
Discover and reflect: search Godot classes and methods, describe classes/objects, and call any method via
ClassDB.Author scenes undoably: create, delete, rename, reparent, duplicate, and move nodes; instance and save scenes; attach scripts and connect signals; set properties and resources; roll back batches on failure.
Write validated GDScript and C#: validate-before-write, script patching, reading scripts, and
build_csharpcompile-checking for .NET projects.Run and debug: play/stop scenes, wait for conditions/nodes, read editor logs, and tail the running game's errors, warnings, and prints with stack traces.
See the running game: take screenshots, snapshot UI controls as structured data, dump the live remote scene tree, find live nodes, read/monitor runtime properties, and poll performance monitors.
Diagnose rendering: use
render_probeto explain why a 3D node is or isn't visible, and switch debug draw modes before screenshots.Manage files and project settings: read/write files, list/search directories, read/set project settings, get project statistics, and apply project templates.
Self-diagnose and assist:
doctorchecks server/edition/security/tool context,helpexplains any tool, and MCP resources/prompts provide structured project views and reusable workflows.
Beckett — MCP for Godot
Stop waiting for Godot.
Beckett is a zero-sidecar Model Context Protocol (MCP) server embedded directly in the Godot 4 editor as a GDScript EditorPlugin. AI agents (Claude and others) drive the editor over HTTP — no Node/Python bridge, no second process, no cloud.
This repository is the free, MIT-licensed Lite edition: the complete inspect → author → run → SEE dev loop (56 tools), for GDScript and C#. The AI can now watch your running game on the free tier: screenshot it, read the live remote scene tree and node state, poll performance monitors, and tail the game's logs. The paid Full edition makes the AI the playtester (it drives input, clicks 2D/3D and UI, and asserts the results), plus a test runner, animation tools, scatter_nodes, background exports, project-wide analysis, and 46 knowledge packs. See What Full adds.
Lite: the AI sees your game. Full: the AI playtests it.
Demo

Related MCP server: godot-devtool
Why
Existing Godot MCP servers either shell out to the CLI (can't play the game, screenshot, or inspect runtime) or run a Node/Python sidecar that relays to a thin in-editor addon. This one makes the addon itself the MCP server, and exposes reflection-generic tools that work on any class via ClassDB — instead of hundreds of hand-coded per-domain wrappers (an anti-pattern: LLMs degrade past ~40 tools).
Highlights
Zero-sidecar —
TCPServerHTTP/JSON-RPC server polled on the editor main thread. No marshalling, nothing extra to install beyond the addon.The AI sees your game (free) —
screenshotthe running game, read the live remote scene tree (get_remote_tree/find_nodes/wait_for_node), read live node state (runtime_get_property/monitor_properties), pollget_performance_monitors, and tailgame_logswith stack traces. The free tier can watch and diagnose the running game; Full closes the loop by driving input and asserting the result.GDScript and C#, one addon, zero sidecar — the C#/.NET dev loop is free too:
build_csharpruns adotnet buildcompile-check that returns structuredfile:line:col+ CS-code diagnostics (safe while the editor is open, no new dependency beyond the .NET SDK a C# project already needs),write_scriptis.cs-aware, and reflection surfaces your C#[GlobalClass]types just like GDScriptclass_name.Reflection-first + discovery —
find_classes/describe_class/find_methodsmake the whole engine surface searchable;describe_object/set_property/call_methodthen drive anyNode/Resource/Object. Reaches TileMap, GPUParticles, AnimationTree, NavMesh, shaders… with no per-domain code.GDScript dev-loop with validate-before-write —
write_script/script_patchparse the code first and refuse to write what doesn't compile (closing the #1 AI-on-Godot failure: hallucinated GDScript). Godot's edge over UE: reload needs no compile step.Undoable authoring — every scene/node mutation goes through
EditorUndoRedoManager(atomic + undoable);batch_executerolls a whole batch back on failure.One-step install — enabling the plugin auto-starts the server and writes
.mcp.json, soclaude/Cursor connects with zero hand-editing (no Node.js to install — the competitor needs it just to try).Security: localhost-only, with exact Host and Origin checks (anti DNS-rebind), a per-project token for new projects, file reads confined to the project, and read-only / allowlist / confirm-destructive gates; auto-start is opt-out (
beckett/autostart=false). SECURITY.md says what is protected, what is not, and how to report a problem.Run → see loop —
play_scene→wait_until→logs_read→screenshot/get_remote_tree→ fix: launch the game, tail its output and errors, then look at the running frame and live scene tree to diagnose. (Full closes the loop autonomously: the AI drives the game and asserts.) Plus MCP Resources + Prompts.Dock panel — status, one-click Start/Stop, copy-client-config, and an AI-effort slider (1–4 in Lite; L4 = See) that caps how many tools are advertised: cheaper model context when you only need a slice. Applies live, no reconnect — the server pushes
notifications/tools/list_changedover its SSE stream and list-changed-aware clients (Claude Code, Cursor, …) re-fetch on the spot.Responsive even unfocused — while MCP traffic is active the server clamps the editor's low-processor sleep, so calls stay fast when you're focused on the terminal instead of the editor (the usual agent setup).
Spec-current MCP — protocol version negotiation, tool annotations (
readOnlyHint/destructiveHint/openWorldHint) on every tool, andstructuredContent(2025-06-18) alongside text results. An audit ring (audit://recent) records the last 200 tool calls — see everything the AI did.
Tools (56) · Resources (6) · Prompts (6)
Fewer tools, on purpose — that's the moat, not a limitation. Most Godot MCPs hand-code one tool per task (
create_sprite,add_collision,make_timer…) — hundreds that still miss classes and flood the model's context (LLMs measurably degrade past ~40 tools). Beckett's are reflection-generic:describe_class/set_property/call_methoddrive any of Godot's 1000+ classes throughClassDB— TileMap, GPUParticles, AnimationTree, shaders, your ownclass_nameor C#[GlobalClass]— with no per-domain code. Don't count tools, count coverage: a smaller, sharper toolset that reaches the whole engine beats a hundred narrow wrappers that don't.
The free Lite edition — the complete inspect → author → run → see loop, for GDScript and C#:
Reflection / discovery:
get_godot_version,find_classes,describe_class,find_methods,describe_object,set_property,call_method,get_scene_treeScene authoring (undoable):
create_node,delete_node,rename_node,reparent_node,duplicate_node,move_node,instance_scene,save_scene,open_sceneGDScript dev-loop:
validate_script,write_script,script_patch,read_script,attach_scriptC#/.NET dev-loop:
build_csharp(adotnet buildcompile-check returning structuredfile:line:col+ CS-code diagnostics, safe while the editor is open, zero new dependency;write_scriptis.cs-aware and C#[GlobalClass]types show up in reflection)Signals:
connect_signal,disconnect_signal,list_signalsResource assets:
create_resource,set_resourceFiles / project:
read_file,write_file,list_dir,search_files,rescan_filesystem,get_project_setting,set_project_settingRun loop:
play_scene,stop_scene,get_play_state,wait_until,logs_readRuntime observation (the AI sees your game):
screenshot,ui_snapshot(every visible Control as structured state in one call),get_remote_tree,find_nodes,wait_for_node,runtime_get_property,monitor_properties,get_performance_monitors,game_logsRender diagnosis:
render_probe(why a 3D node is or is not on screen, as data: visibility chain, frustum, cull mask, material cull mode, triangle winding) andset_debug_draw(switch the running game's debug draw mode, thenscreenshotone render stage)Project / authoring helpers:
get_project_statistics,apply_template,batch_execute,doctor(one-call self-diagnosis: edition, effort cap, server and auth state, client configs, and what the tool list costs your context per tier),help(any tool's full argument catalogue, on demand)MCP Resources:
scene://tree,scene://selection,project://settings,assets://list,log://output,audit://recentMCP Prompts:
inspect_node,audit_scene,setup_2d_player,fix_script_errors,build_test_fix,make_game
What Full adds
The Full edition is the same core plus a premium layer that makes the AI the playtester: it sees the screen, presses the buttons, and verifies the result. 92 tools, 46 skill packs total:
The AI drives:
simulate_input, UI clicks in 2D + 3D (click_button_by_text/click_control/click_node3d/click_world),scroll/drag,get_control_rect/find_ui_elements, liveruntime_call/runtime_set_property, andrecord_input/replay_input.The AI verifies:
assert_node_state,assert_screen_text,assert_scene,compare_screenshots, plus the in-editor test runner (test_run).Author + ship:
animation_manage(keys / tracks / presets),scatter_nodes(Scene-Paint mass placement), backgroundexport_project+job_status, project-wide analysis (find_unused_resources,detect_circular_dependencies), and the Godot Asset Store / Library browser-installer (asset_lib_search/asset_lib_info/asset_lib_install).46 skill knowledge packs (
list_skills/load_skill): gdscript, particles, animation, ui, physics, multiplayer, mobile, and more, so reflection reaches each domain with no per-domain tools.
Lite ships the game-side runtime (addons/beckett/runtime/mcp_runtime.gd, MIT source) that Full's drive tools use, and that runtime understands the drive commands. Lite's tools never send them and Lite's bridge refuses them, so Lite sees the running game without driving it. This is a product boundary, not a sandbox; SECURITY.md has the details.
Full is a one-time purchase ($15) with lifetime updates: https://beckettlabs.itch.io/beckett-godot-mcp
How it compares
Beckett is one of only a few embedded (zero-sidecar) servers in the field, and its free tier includes seeing the running game, as Native's does. The other players have real strengths (raw tool count, mindshare, breadth), so here's an honest side-by-side. (Competitor figures are their own published numbers; they ship far more hand-coded per-domain tools, which is a different design choice, not strictly "more capability": see Why.)
Beckett Lite (free, MIT) | Beckett Full ($15) | CLI shell-out (e.g. Coding-Solo, free) | Sidecar (godot-mcp-pro, $15, Node 18+) | Native (free, embedded, 4.6+ only) | |
Zero sidecar (no Node/Python) | ✅ | ✅ | ❌ (Node CLI shell-out) | ❌ (Node 18+ + TS server) | ✅ (embedded) |
The AI sees the running game (screenshot, live tree, live state) | ✅ free | ✅ | ⚠️ CLI debug output only | ✅ (paid) | ✅ (free) |
The AI drives + asserts (playtest: input, clicks, asserts) | ❌ | ✅ | ❌ | ✅ (input record/replay) | ⚠️ partial |
Validate-before-write (refuses non-compiling GDScript) | ✅ | ✅ | ❌ | ❌ | ❌ |
C# + GDScript | ✅ | ✅ | ❌ (GDScript) | ❌ (GDScript) | ❌ (GDScript) |
Godot 4.2+ | ✅ | ✅ | varies | varies | ❌ (4.6+ only) |
Tool count | 56 | 92 | ~12 | ~163 | 154 |
No trash talk intended: Coding-Solo is the mindshare leader (~4,000★), godot-mcp-pro ships the broadest curated toolset (~163) with input record/replay, and Native gives away 154 tools embedded. Beckett's bet is a smaller reflection-generic surface that reaches the whole engine, validate-before-write, both languages, 4.2+ reach, and the AI seeing your game in the free tier.
Use
Install from the editor. In Godot, open the Asset Store tab (AssetLib before 4.7), search "Beckett", and install (Asset Store listing, Asset Library #5296). Or copy
addons/beckett/into your project manually.Enable Beckett in Project → Project Settings → Plugins (works on Godot 4.2+, 4.4+ recommended; CI-verified on 4.4.1, and on 4.6.3 & 4.7.2 across Windows, macOS and Linux). Enabling it auto-starts the server and writes
.mcp.json. (Opt out:beckett/autostart=false,beckett/auto_write_client_config=false. Other options:BECKETT_PORTdefault8770,BECKETT_TOKEN,BECKETT_READONLY=1,BECKETT_ALLOWLIST,BECKETT_CONFIRM_DESTRUCTIVE=1. Panel has Start/Stop.)Connect your client. For Claude Code, just run
claudein the project; the auto-written.mcp.jsonwires it up (/mcp→ beckett). For Cursor/others, point athttp://127.0.0.1:8770/mcp(Streamable HTTP) or press the panel's Connect Detected Clients button. See INSTALL.md.
Status
This is the free, MIT-licensed Lite edition — the inspect → author → run → see core: reflection/discovery, scene & script authoring for GDScript and C# (with build_csharp compile-check), signals, resource create/assign, files & project settings, the play → wait → logs_read dev loop, and the runtime-observation tools that let the AI see the running game (screenshot, get_remote_tree, live node state, perf monitors, game_logs), plus Resources + Prompts + dock panel. 56 tools. Built and verified live on Godot 4.4.1, 4.6.2 and 4.7 (headless editor + a real HTTP MCP client), and CI-tested on every push across Windows, Linux, and macOS.
The Full edition adds the agent-driven play-test layer (the AI drives input, clicks 2D/3D and UI, and asserts results): the test runner (test_run), animation tools (animation_manage), scatter_nodes, background export jobs, project-wide analysis, and the 46 bundled skill packs. It playtests the running game.
License
Lite edition — MIT (this repository). Free and open-source: use it, fork it, ship it. See LICENSE.
The Full edition (the agent-driven play-test layer, background export jobs, and the skill packs) is a separate commercial product — one-time purchase with lifetime updates.
Beckett is a third-party tool, not affiliated with or endorsed by the Godot Foundation. "Godot" is a trademark of the Godot Foundation.
Available Tools
56 toolsapply_templateA
Instantiate a bundled (or project) template into res:// in one call — copies its files and, if the template declares a main_scene, sets and opens it. Generic: a template can be a game starter, a UI screen, a settings menu, a test harness. Project templates under res://.beckett/templates/ override bundled ones. Call with no 'template' to list what's available.
Inputs: force, template.
attach_scriptA
Attach a script (res:// path) to a node in the open scene (undoable).
Inputs: path (required), target (required).
batch_executeA
Run several tool calls in one request, in order. steps = [{tool, args}]. Stops at the first failure (stop_on_error, default true). When a step fails, scene edits made by the batch are rolled back via the editor undo history (rollback, default true); file/resource writes are not. Use to collapse multi-step authoring (create node → set props → attach script) into one atomic call. ok per step means the handler completed - verify EFFECTS with a trailing read-back step (a get_* or describe_object call; assert_scene / assert_node_state in Full) before trusting a mutation batch.
Inputs: steps (required), rollback, stop_on_error.
build_csharpARead-only
Compile-check a C#/.NET Godot project with dotnet build, returning structured diagnostics (errors/warnings with file:line:col + CS-code). Isolated build (scratch output) — never touches the editor's loaded assembly, so it's safe while the editor is open. Auto-detects the .csproj if omitted. Needs the .NET SDK, checked first (Godot 4.8 needs SDK 10): a missing or too-old one comes back as a plain error saying what to install, not as build noise. First build restores packages (slower); incremental ~1-3s. Use after editing .cs — the GDScript compile-gate (write_script) does NOT cover C#.
Inputs: csproj, configuration.
call_methodADestructive
Invoke a method on a resolved object. args = a positional array, coerced to the declared param types: vectors accept [x,y,z] / {"x":..} / "x y z", colors hex or [r,g,b,a], object params a node name/path or res:// path. set / set_deferred / set_indexed hold the value to the property's type, as set_property does. Wrong types or counts return an ERROR (never a silent no-op). Returns the result as JSON.
Inputs: method (required), target (required), args.
connect_signalA
Connect a node's signal to a method on another node, persisted into the scene (undoable). from/to = node path/name in the open scene.
Inputs: to (required), from (required), method (required), signal (required).
create_nodeA
Create a node of the given class and add it to the open scene (undoable). parent = a node path/name (default: scene root).
Inputs: type (required), name, parent.
create_resourceADestructive
Create a Resource of the given class and save it to a res:// path (.tres). Optional 'properties' dict sets initial values.
Inputs: path (required), class (required), properties.
delete_nodeBDestructive
Remove a node from the open scene (undoable).
Inputs: target (required).
describe_classARead-only
List a class's properties and methods (with signatures) so you know exactly what to set_property / call_method. The discovery key for full domain coverage. Also covers built-in Variant types (Vector3, Transform3D, Basis, Color, String...) and your class_name types.
Inputs: class (required), inherited.
describe_objectARead-only
Dump a live object's properties as JSON. target = a res:// path, a node name/path in the OPEN scene, or a class name (falls back to describe_class). While a game is running it also resolves live nodes (/root/Main/Player), the same paths runtime_get_property takes; the answer says which scope it came from, since the edited scene and the running game share one path syntax but are different worlds.
Inputs: target (required).
disconnect_signalA
Disconnect a previously connected signal (undoable).
Inputs: to (required), from (required), method (required), signal (required).
doctorARead-only
Beckett self-diagnosis — one call answers 'why can't the agent see or do X?'. Reports: edition (Lite/Full), the effort dial vs its ceiling AND where the cap comes from (a beckett/effort= line committed in project.godot silently trims every clone's tool list), advertised-vs-ceiling tool counts, dock-disabled tools, server/port/auth state, per-client config freshness (does each written config still carry the CURRENT endpoint URL, and does a Claude Desktop bridge pin an exact mcp-remote version?), runtime-bridge liveness, what this tool surface costs your context (exact tools/list bytes and approximate tokens for every effort tier, measured on THIS install, so you can price a tier before dialing to it; plus what Claude Code's tool search holds upfront, the always_load tools), whether the game plays EMBEDDED in the editor's Game workspace or in its own window (embedded means the Suspend button freezes every runtime call and window-mode asserts can never pass), and whether the editor auto-reloads externally-changed scripts (off = every script this server writes waits behind a modal the human must click), for C# projects whether an installed .NET SDK satisfies this engine (4.8 needs SDK 10), and the known Godot bugs for this exact version (known_issues, never part of ok). Run this FIRST when tools seem missing, counts look wrong, or calls fail unexpectedly.
Inputs: no named parameters. Returns: ok, tools, dotnet, editor, +12 more
duplicate_nodeA
Duplicate a node (with its children) under the same parent (undoable). Optional 'name' for the copy.
Inputs: target (required), name.
find_classesARead-only
Search classes by name substring — engine classes, built-in Variant types (Vector3, Transform3D, Color...) AND your project's own types (GDScript class_name + C# [GlobalClass]). Optional 'base' restricts to subclasses (e.g. base=Node2D). The discovery entry point — pair with describe_class.
Inputs: max, base, query.
find_methodsARead-only
Search methods by name substring, optionally restricted to a class (incl. inherited). Covers engine classes, built-in Variant types (Vector3, Transform3D, Color...) and your class_name types. Object methods are invokable via call_method; kind=builtin results are called on values in GDScript. An unknown class is an error, never a silent search of everything.
Inputs: query (required), max, class.
find_nodesARead-only
Find LIVE nodes in the RUNNING game by type and/or name; returns their paths to feed into runtime_get_property (in Full also runtime_call and runtime_set_property). 'class' matches native classes AND custom class_name scripts (is_class alone misses custom nodes, which read as @Node@NN). name=substring on the node name. path=scope root (default scene root). recursive=true. max=cap (default 100).
Inputs: max, name, path, class, +1 more.
game_logsARead-only
Read the RUNNING game's captured output off the runtime channel (real-time, no file logging): runtime SCRIPT errors WITH stack traces, push_error/push_warning, and print(). This is the play->see-error->fix signal — the blind spot logs_read (file-based) can't reliably cover. level=error (default: errors+script+shader) | warning (adds warnings) | all (adds print/stderr). limit=newest N (default 100), filter=substring, clear=true empties the buffer after reading.
Inputs: clear, level, limit, filter.
get_godot_versionARead-only
Return the running Godot engine version info.
Inputs: no named parameters.
get_performance_monitorsARead-only
Profiling: read Performance monitors (fps, frame time, memory, object/node counts, draw calls, video mem, physics) — measured engine counters, never estimates. target=game (default with a play session) | editor. duration_s>0 samples over time and returns per-monitor {min, avg, p95, max}. Sampling rules and why an editor-target window is refused: help(tool="get_performance_monitors").
Inputs: series, target, duration_s, interval_ms. Returns: stats, series, target, samples, +3 more
get_play_stateARead-only
Report whether a scene is playing, whether the runtime channel to the game is connected, and debugger_break (the game is paused in the editor's debugger).
Inputs: no named parameters.
get_project_settingARead-only
Read a ProjectSettings value by its property path (e.g. application/run/main_scene). Pass it as 'setting' ('name' is also accepted).
Inputs: name, setting.
get_project_statisticsARead-only
Project overview: file/script/scene/resource counts, total GDScript lines, autoloads, main scene, input-action count, Godot version. Read-only static scan.
Inputs: no named parameters.
get_remote_treeARead-only
Dump the live scene tree of the RUNNING game (runtime counterpart of get_scene_tree). SCOPE IT to stay under token limits — a full game tree blows the budget. path=subtree root (name, relative, or absolute /root/...); depth=levels (-1=all); max_nodes (default 250); max_children per node (default 50); collapse=true groups runs of identical leaf siblings (e.g. '8x CPUParticles2D'); state=true adds game-owned state (help(tool="get_remote_tree")). Returns {tree, node_count, truncated?}.
Inputs: path, depth, state, collapse, +2 more.
get_scene_treeARead-only
Return the node tree of the scene currently open in the editor (name/class/script, nested).
Inputs: no named parameters.
helpARead-onlyIdempotent
Full syntax for one tool - the argument catalogue and worked examples that descriptions no longer carry. Call help(tool="NAME") before a call you are unsure of; bare help() lists what is documented.
Inputs: tool.
instance_sceneA
Instantiate a packed scene (res://*.tscn, or an imported model such as .glb) as a child in the open scene (undoable). It instances the scene the way the editor does, so the saved scene stores it as an instance of the file and later edits to the file show up in this scene.
Inputs: scene (required), name, parent.
list_dirARead-only
List entries (dirs + files) of a res:// directory.
Inputs: path.
list_signalsARead-only
List a node's signals and their current connections (target node + method).
Inputs: target (required).
logs_readARead-only
Tail Godot's log FILE (the editor session and any played game log here). For the RUNNING game's errors/stack traces/prints in REAL TIME, prefer game_logs (runtime channel, no file needed) — this file reader is a fallback and needs file logging enabled (off by default; the result tells you how). Optional: level='error'|'warning', 'filter' substring, 'lines' (default 200), 'path' to override.
Inputs: path, level, lines, filter.
monitor_propertiesARead-only
Sample a node's property in the running game over several frames (detect movement/changes). Returns the sample series.
Inputs: path (required), property (required), samples, interval_ms.
move_nodeA
Reorder a node within its parent to a new child index (undoable).
Inputs: target (required), to_index (required).
open_sceneA
Open a scene by res:// path in the editor (makes it the edited scene).
Inputs: path (required).
play_sceneA
Play a scene in the editor. 'scene' (res://) plays a specific scene; current=true plays the open scene; otherwise the project's main scene. Then wait_until condition=play_started, and logs_read for errors. on_ready queues runtime property writes applied the moment the new game connects — the restart boundary batch_execute cannot cross. quiet=true plays muted and off-screen so the person keeps working. Script errors do not pause the game (4.5+): game_logs has them. on_ready shape, retries, what quiet does per run mode: help(tool="play_scene").
Inputs: quiet, scene, current, on_ready.
read_fileARead-only
Read a text file by res:// (or user://) path.
Inputs: path (required).
read_scriptARead-only
Read a script/text file from res://.
Inputs: path (required).
rename_nodeA
Rename a node in the open scene (undoable). Like the Scene dock, it also respells every relative NodePath in the scene that leads through the node (an exported NodePath, Array[NodePath] or Dictionary entries, RemoteTransform3D.remote_path, a %unique path) in the same undo step, and the reply lists them. It refuses a sibling's name, and a %unique name that another node already holds. Characters a node name cannot hold are replaced the way Godot replaces them, and the reply gives the name the node ended up with.
Inputs: name (required), target (required).
render_probeARead-only
Ask WHY a 3D node is or is not on screen, as data instead of pixels — the "node exists, visible is true, log is clean, and I still see nothing" case. Returns a 'warnings' list naming the stage that broke, or a verdict that the geometry does reach the camera. USE THIS BEFORE tuning lighting, fog, exposure or palette on anything you cannot clearly see. The stages it checks: help(tool="render_probe").
Inputs: nth, name, path, class, +1 more.
reparent_nodeA
Move a node under a new parent in the open scene (undoable).
Inputs: target (required), new_parent (required).
rescan_filesystemAIdempotent
Make the editor see files written OUTSIDE it (your own file tools, git, a generator). Scripts sync at once, so a new class_name resolves right away for validate_script / write_script; new assets import in a background scan (the result says while it is still scanning). Pass 'paths' to sync just those files. write_file, write_script and script_patch already do this for what they write.
Inputs: paths.
runtime_get_propertyARead-only
Read a property of a node in the RUNNING game. Address by path (node path/name) OR a live selector: class (native or custom class_name) / name / text [+ nth, default 0]. The selector resolves fresh each call — no need to re-fetch volatile @Node@NN paths. Returns the value plus the 'resolved' path that matched.
Inputs: property (required), nth, name, path, +3 more.
save_sceneA
Save the scene currently open in the editor. Pass 'path' (res://) to save-as.
Inputs: path.
screenshotARead-only
Capture an image the agent can see. target=game (default) captures the RUNNING game; target=editor the editor's 2D or 3D view (PNG only). A bare call caps the long edge at max_dim=1280: pass scale, region, max_dim=0, format or save_to to opt out. annotate=ui draws numbered Set-of-Mark boxes and returns the legend. For pure functional state ui_snapshot is cheaper. Token dials, game pixels, delivery: help(tool="screenshot").
Inputs: scale, format, region, target, +7 more.
script_patchADestructive
Surgically edit an existing res:// file without rewriting it whole. edits = an ordered array; each item is {find, replace[, all]} (find must match EXACTLY once unless all:true), {append: text}, or {prepend: text}. Atomic + safe: nothing is written if any anchor is missing/ambiguous or (for .gd) the result fails to compile. Reads the file back (disk_verified). Prefer this over write_script for small changes.
Inputs: path (required), edits (required), validate.
search_filesARead-only
Search file contents under res:// for a substring (or regex with regex=true). Returns file:line matches.
Inputs: query (required), ext, max, regex.
set_debug_drawA
Switch the RUNNING game's viewport debug draw mode, then screenshot to see one render stage in isolation. unshaded = albedo only (clears lighting/fog/exposure as suspects in one shot). wireframe = is the geometry even there (culled or degenerate meshes show as nothing). overdraw = transparency cost. normal_buffer = flipped or NaN normals. lighting = light contribution only. normal = back to the real image. Reach for this FIRST when the picture is wrong; render_probe then answers the same question in numbers.
Inputs: mode (required).
set_project_settingADestructive
Set a ProjectSettings value and persist project.godot. The property path goes in 'setting' ('name' is also accepted); e.g. set application/run/main_scene to res://main.tscn. A setting that already holds a typed value keeps its type: colors take "#rrggbb" or [r,g,b,a], vectors [x,y]. A value that cannot convert is refused, not stored.
Inputs: value (required), name, setting.
set_propertyADestructive
Set a property on a resolved object (undoable). value is converted to the type the property declares: vectors take [x,y,z], "x y z" or "(x, y, z)", colors "#rrggbb", a name or [r,g,b,a], an enum its number, an object property a res:// path (loaded) or null. A value that does not fit is an ERROR and nothing is written. Every spelling: help(tool="set_property").
Inputs: value (required), target (required), property (required), save.
set_resourceA
Assign a resource to a node's property (undoable). Use 'resource' (res:// path to load) OR 'class' (mint a new inline sub-resource of that class). e.g. set Sprite2D.texture from a path, or a fresh RectangleShape2D on CollisionShape2D.shape.
Inputs: target (required), property (required), class, resource.
stop_sceneA
Stop the running play session.
Inputs: no named parameters.
ui_snapshotARead-only
One-call UI snapshot of the RUNNING game: every visible Control as structured data (path, class, text, rect, and the semantic state pixels cannot tell you: disabled, focused, checked, value, selected, editable, tooltip) plus per-control honesty flags. For FUNCTIONAL UI checks this replaces a screenshot plus a read per control; keep screenshot for visual/render bugs. Every field, and the free since_hash re-read: help(tool="ui_snapshot").
Inputs: path, max_nodes, occlusion, since_hash, +1 more.
validate_scriptARead-only
Parse/compile GDScript WITHOUT writing it. Pass 'content' (source) or 'path' (res://). Returns whether it compiles, plus the GDScript warnings the editor would show (unused variables, shadowing, integer division...). Use before write_script to catch hallucinated APIs. A class_name from a file written outside the editor is registered first. When validating 'content' destined for an existing file, ALSO pass its 'path' so a real cross-file class_name duplicate is still reported.
Inputs: path, content, warnings.
wait_for_nodeARead-only
Block until a node appears in the RUNNING game (by path/name) or timeout. Use after play_scene to sync before you read the game (or, in Full, drive it).
Inputs: path (required), timeout_ms.
wait_untilARead-only
Wait for a condition. Blocks the editor at most ~1.5 s per call — longer would stall the editor's own game-launch pipeline and background jobs (they need main-thread frames). If not met yet it answers 'not yet': just call it again. condition = play_started | play_stopped | game_connected | seconds:N | file_exists:res://path.
Inputs: condition (required), timeout_ms.
write_fileADestructive
Write a text file under res:// (or user://), path-traversal guarded. Reads it back (disk_verified). Refreshes the editor filesystem. If the file is a .tscn the editor currently has OPEN, the result says so: Godot prompts the human to reload it and until they do the editor still holds the old version (scripts have no such problem, the editor auto-reloads them). Set beckett/auto_reload_scenes=true to reload open scenes automatically. Prefer the scene tools (create_node / set_property / save_scene) over writing .tscn text at all - editor-side edits never go stale.
Inputs: path (required), content (required).
write_scriptADestructive
Write a GDScript (or other text, e.g. .cs) file under res://. GDScript is validated first by default — refuses code that doesn't compile; non-.gd files (C#, config…) are written as-is (use build_csharp to compile-check C#). Set validate=false to force. Reads the file back (disk_verified).
Inputs: path (required), content (required), validate.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 56 tools
Several tool pairs overlap: read_file/read_script, write_file/write_script, logs_read/game_logs, get_scene_tree/get_remote_tree, and describe_class/describe_object. Descriptions clarify editor-vs-runtime and text-vs-GDScript context, so an agent can often choose correctly, but the redundancy leaves real misselection risk.
Names are predominantly snake_case and action-oriented (find_nodes, create_node, set_property), with minor exceptions like logs_read, script_patch, game_logs, ui_snapshot, and single-word doctor/screenshot/help. The pattern is readable and mostly predictable rather than chaotic.
At 56 tools the surface is far beyond the 3-15 sweet spot and past the 50+ extreme threshold for agent tool lists. The broad Godot domain explains some breadth, but batch_execute, help, doctor, and effort tiers largely compensate for an over-scoped surface.
The set covers scene CRUD, scripts, files, signals, resources, project settings, runtime inspection, profiling, screenshots/UI, templates, C# builds, and diagnostics. Gaps remain around runtime mutation (no runtime_set_property/runtime_call in this list), file/resource deletion, and input interaction, but most 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.
Build, run and publish 3D games in the Zero engine from Claude Code, Cursor or Codex, over MCP.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to control Unreal E…
Build your own tools from chat: design, test and host them on a shareable MCP server URL.
Related MCP Servers
- AlicenseAqualityDmaintenanceGodot 4 MCP server with: Test running (GUT/GdUnit4) with structured pass/fail results API docs search with 30+ Godot 3→4 migration mappings Script analysis detecting 10 common GDScript pitfalls Scene/resource file parsing with antipattern detection Viewport screenshot capture LSP diagnostics from Godot's language server TypeScript, cross-platform (macOS/Windows/Linux), published on npm893 npm8MIT
- AlicenseAqualityFmaintenanceA Godot 4 MCP server for AI-assisted project inspection, editing, validation, and runtime automation via stdio and optional WebSocket bridge.389MIT
- AlicenseNot gradedqualityCmaintenanceA security-first MCP server and Godot editor addon enabling AI agents to observe and control Godot games through bounded, permission-gated tools for debugging, input automation, and project editing.MIT
- AlicenseNot gradedqualityBmaintenanceThe most advanced MCP server for Godot Editor that lets AI assistants operate directly inside your running Godot project for scene creation, script generation, UI authoring, and more.55MIT