Skip to main content
Glama
Beckett — MCP for Godot

Beckett — MCP for Godot

by beckettlab

Server Configuration

Describes the environment variables required to run the server.

NameRequiredDescriptionDefault
BECKETT_PORTNoPort for the MCP server (default 8770)8770
BECKETT_TOKENNoOptional bearer token for authentication
BECKETT_READONLYNoSet to 1 to enable read-only mode
BECKETT_ALLOWLISTNoComma-separated list of allowed paths or patterns
BECKETT_CONFIRM_DESTRUCTIVENoSet 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

CapabilityDetails
tools
{
  "listChanged": false
}

Tools

Functions exposed to the LLM to take actions

NameDescription
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 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#.

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

NameDescription

No prompts

Resources

Contextual data attached and managed by the client

NameDescription

No resources

TDQS

A3.6/5.0

Scored across 56 tools

Disambiguation3/5

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.

Naming Consistency4/5

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.

Tool Count1/5

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.

Completeness4/5

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

ActivityMaintained
ResponsivenessOutdated data