Beckett — MCP for Godot
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| BECKETT_PORT | No | Port for the MCP server (default 8770) | 8770 |
| BECKETT_TOKEN | No | Optional bearer token for authentication | |
| BECKETT_READONLY | No | Set to 1 to enable read-only mode | |
| BECKETT_ALLOWLIST | No | Comma-separated list of allowed paths or patterns | |
| BECKETT_CONFIRM_DESTRUCTIVE | No | Set to 1 to require confirmation for destructive actions |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
This server publishes no instructions, or was last inspected before Glama recorded them.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| apply_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. |
| attach_scriptA | Attach a script (res:// path) to a node in the open scene (undoable). |
| 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. |
| build_csharpA | Compile-check a C#/.NET Godot project with |
| call_methodA | 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. |
| 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. |
| 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). |
| create_resourceA | Create a Resource of the given class and save it to a res:// path (.tres). Optional 'properties' dict sets initial values. |
| delete_nodeB | Remove a node from the open scene (undoable). |
| describe_classA | 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. |
| describe_objectA | 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. |
| disconnect_signalA | Disconnect a previously connected signal (undoable). |
| doctorA | 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. |
| duplicate_nodeA | Duplicate a node (with its children) under the same parent (undoable). Optional 'name' for the copy. |
| find_classesA | 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. |
| find_methodsA | 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. |
| find_nodesA | 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). |
| game_logsA | 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. |
| get_godot_versionA | Return the running Godot engine version info. |
| get_performance_monitorsA | 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"). |
| get_play_stateA | 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). |
| get_project_settingA | Read a ProjectSettings value by its property path (e.g. application/run/main_scene). Pass it as 'setting' ('name' is also accepted). |
| get_project_statisticsA | Project overview: file/script/scene/resource counts, total GDScript lines, autoloads, main scene, input-action count, Godot version. Read-only static scan. |
| get_remote_treeA | 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?}. |
| get_scene_treeA | Return the node tree of the scene currently open in the editor (name/class/script, nested). |
| helpA | 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. |
| 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. |
| list_dirA | List entries (dirs + files) of a res:// directory. |
| list_signalsA | List a node's signals and their current connections (target node + method). |
| logs_readA | 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. |
| monitor_propertiesA | Sample a node's property in the running game over several frames (detect movement/changes). Returns the sample series. |
| move_nodeA | Reorder a node within its parent to a new child index (undoable). |
| open_sceneA | Open a scene by res:// path in the editor (makes it the edited scene). |
| 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"). |
| read_fileA | Read a text file by res:// (or user://) path. |
| read_scriptA | Read a script/text file from res://. |
| 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. |
| render_probeA | 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"). |
| reparent_nodeA | Move a node under a new parent in the open scene (undoable). |
| rescan_filesystemA | 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. |
| runtime_get_propertyA | 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. |
| save_sceneA | Save the scene currently open in the editor. Pass 'path' (res://) to save-as. |
| screenshotA | 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"). |
| script_patchA | 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. |
| search_filesA | Search file contents under res:// for a substring (or regex with regex=true). Returns file:line matches. |
| 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. |
| set_project_settingA | 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. |
| set_propertyA | 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"). |
| 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. |
| stop_sceneA | Stop the running play session. |
| ui_snapshotA | 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"). |
| validate_scriptA | 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. |
| wait_for_nodeA | 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). |
| wait_untilA | 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. |
| write_fileA | 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. |
| write_scriptA | 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). |
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 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.