Beckett - MCP for Godot

Beckett — MCP for Godot

Stop waiting for Godot.

[CI] [Discord] [License: MIT] [Godot 4.2+] [MCP] [Release] [Stars] [Last commit]

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

[Watch Beckett drive Godot]

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 — TCPServer HTTP/JSON-RPC server polled on the editor main thread. No marshalling, nothing extra to install beyond the addon.
• The AI sees your game (free) — screenshot the 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), poll get_performance_monitors, and tail game_logs with 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_csharp runs a dotnet build compile-check that returns structured file:line:col + CS-code diagnostics (safe while the editor is open, no new dependency beyond the .NET SDK a C# project already needs), write_script is .cs-aware, and reflection surfaces your C# [GlobalClass] types just like GDScript class_name.
• Reflection-first + discovery — find_classes / describe_class / find_methods make the whole engine surface searchable; describe_object / set_property / call_method then drive any Node / Resource / Object. Reaches TileMap, GPUParticles, AnimationTree, NavMesh, shaders… with no per-domain code.
• GDScript dev-loop with validate-before-write — write_script / script_patch parse 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_execute rolls a whole batch back on failure.
• One-step install — enabling the plugin auto-starts the server and writes .mcp.json, so claude/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_changed over 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, and structuredContent (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_method drive any of Godot's 1000+ classes through ClassDB — TileMap, GPUParticles, AnimationTree, shaders, your own class_name or 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_tree
• Scene authoring (undoable): create_node, delete_node, rename_node, reparent_node, duplicate_node, move_node, instance_scene, save_scene, open_scene
• GDScript dev-loop: validate_script, write_script, script_patch, read_script, attach_script
• C#/.NET dev-loop: build_csharp (a dotnet build compile-check returning structured file:line:col + CS-code diagnostics, safe while the editor is open, zero new dependency; write_script is .cs-aware and C# [GlobalClass] types show up in reflection)
• Signals: connect_signal, disconnect_signal, list_signals
• Resource assets: create_resource, set_resource
• Files / project: read_file, write_file, list_dir, search_files, rescan_filesystem, get_project_setting, set_project_setting
• Run loop: play_scene, stop_scene, get_play_state, wait_until, logs_read
• Runtime 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_logs
• Render 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) and set_debug_draw (switch the running game's debug draw mode, then screenshot one 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://recent
• MCP 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, live runtime_call / runtime_set_property, and record_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), background export_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.)

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

1. 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.
2. 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_PORT default 8770, BECKETT_TOKEN, BECKETT_READONLY=1, BECKETT_ALLOWLIST, BECKETT_CONFIRM_DESTRUCTIVE=1. Panel has Start/Stop.)
3. Connect your client. For Claude Code, just run claude in the project; the auto-written .mcp.json wires it up (/mcp → beckett). For Cursor/others, point at http://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.