<div align="center"> <img src="./icon.png" width="96" alt="godot-mcp-bridge" />

godot-mcp-bridge

An AI that works with you in the Godot editor — not instead of you.

</div>

Every Godot MCP server lets an AI drive the editor. This one also tells the AI what you just did — the scene you opened, the node you selected, the file you saved — so you can both work in the same project at the same time without stepping on each other. Add a real step-debugger, scope-aware refactoring through Godot's language server, live-tree edits that never clobber your unsaved work, and 231 tools that were each verified against a running editor rather than just written.

Started as a fork of tomyud1/godot-mcp (MIT licensed) and has since diverged substantially — see CHANGELOG.md.

---

💬 What you'd actually say to it

"The player falls through the floor sometimes. Set a breakpoint in _physics_process and tell me what velocity is when it happens."

"Build me an enemy: CharacterBody2D, circle collider, sprite, patrol script, and put it in the enemies group."

"Run the game, press jump, screenshot it, and tell me if the animation played."

"Which of my resources aren't referenced by anything anymore?"

"Export a Windows debug build and tell me when it's done."

Under the hood that's a breakpoint hit read from a paused frame, a scaffolded scene tree, a runtime input + screenshot loop, a dependency sweep, and an async headless build — but you don't have to know which tool does which.

<details> <summary>What a debug session actually returns</summary>

// debug_launch({scene: "res://scenes/level.tscn"})
{ "state": "stopped", "stopped_reason": "breakpoint", "hit_breakpoint": true }

// debug_stack_trace()
{ "frames": [{ "name": "_physics_process", "line": 17,
               "source": ".../scenes/player.gd" }] }

// debug_variables({variables_reference: 1})   ← the Locals scope
{ "variables": [{ "name": "delta",     "value": "0.01666666666667" },
                { "name": "direction", "value": "<null>" }] }

// debug_evaluate({expression: "velocity"})
{ "result": "(0.0, 0.0)" }

Real output from the test project — delta is exactly 1/60, matching its 60 Hz physics tick.

</details>

---

✨ Why this one

It's bidirectional. The AI can poll get_editor_activity to see what you just did in the editor — selection, scene open/close/save, script focus, resource saves, asset reimports, undo/redo, which screen you're on — tagged human vs its own actions. It finds out you moved something without having to ask. Every other Godot MCP is one-directional: the AI drives, and is blind to you. (Checked by reading the source of 12 competing servers in July 2026, not their READMEs.)

It doesn't clobber your work. Many Godot MCP servers edit your .tscn files on disk. If you have that scene open with unsaved changes, they silently overwrite it. Here, when a scene is open, every mutating tool edits the live editor tree instead — your unsaved edits survive and every change goes through Godot's undo system (Ctrl+Z works). Closed scenes still edit on disk as usual.

The claims are tested, not asserted. 526 GDScript checks against the tool handlers, 147 Node tests for the bridge and the tool registry, and 43 that drive a real Godot editor — creating scenes, mutating one that is open, launching an actual game — on every push, on both Godot 4.5 and 4.7. Every one of the tools that writes to your project has automated coverage.

That suite is not decoration; it is where the bugs came from. It caught close_scene_tab being broken on 4.5 (the minimum this README promises), a run_scene that froze the whole editor for its entire timeout on every single call, and a res:// texture path that five different tools accepted and silently threw away. Each of those was found by a test that failed, not by reading the code — and each is in CHANGELOG.md with what it cost.

See Limitations for what it still can't do.

More of what it does:

• Step-debugger — set breakpoints, step, read the real call stack and frame variables, evaluate expressions in the paused frame, over Godot's own Debug Adapter. Stop at the failure and look at actual values instead of inferring them from print() output.
• Real headless export — builds an actual game binary via a shadow-workspace clone, asynchronously, without freezing the editor (export_project → get_export_status).
• Runs your real tests — run_gut_tests executes your GUT unit suite (sync or async) and reports pass/fail, so the AI acts on real results instead of guessing.
• Drives the running game — call methods, set properties, await signals, game_eval a snippet, record/replay input, snapshot the live tree, even a multiplayer peer-spawn harness (spawn_headless_peers) — deterministic playtesting without screenshots.
• Sandboxed paths — every path is guarded against traversal outside the project (the class of bug behind CVE-2026-15522 in another server).
• Writes the boilerplate for you — wire_signal connects a signal and generates the correctly-typed handler; generate_onready_refs emits typed @onready vars for a subtree; scaffold_entity builds a character (body + collision shape resource + sprite
  • movement script) in one call; scaffold_state_machine lays out a working FSM. Physics layers can be set by name instead of bit indices.
• Tells you what's rotting — find_unused_resources, detect_circular_dependencies, analyze_scene_complexity, and analyze_signal_flow (which catches connections whose handler doesn't exist — a bug that otherwise only shows up at runtime).
• Asks what changed, not for everything again — scene_diff takes a snapshot id and then returns only the added, removed and modified nodes (with before/after values), so the agent stops paying for a full read_scene every time it looks back. It catches your edits too, not just its own.
• Catches multiplayer bugs that fail silently — mp_diagnose flags an .rpc() call to a method with no @rpc annotation, a synchronizer replicating nothing, and a spawner whose spawn_path goes nowhere. None of those error when you write them; all of them look like "the client is broken" when a second peer joins.
• Visual regression — compare_screenshots diffs two frames and reports the changed percentage and region, so "did my change actually alter the screen?" has an answer.
• Tests your UI like a human would — click a button by its visible caption (click_control_runtime({text: "Start"}), which refuses and lists candidates if the text is ambiguous), then assert what's on screen with assert_screen_text — reading the live Control tree, so it works headless with no OCR.
• Localization that doesn't half-work — sync_localization registers the .translation files Godot generated from your CSV (the manual step that silently makes a language never load) and reports every key you haven't translated yet, per locale.
• Setup that explains itself — npx godot-mcp-bridge install installs and enables the addon in one command; doctor diagnoses a broken setup; diagnose_connection tells the AI exactly why the editor isn't connecting.
• Fast + robust — batch_execute / batch_scene_edit cut N calls to one; heavy reads (read_scene, scene_tree_dump, classdb_query) take max_depth/filter to stay token-cheap; only 37 tools load by default so the agent stays focused. Measured, not claimed — see below.
• Symbol-accurate refactoring — gd_rename and gd_references go through Godot's language server, so they understand scope: renaming a local speed won't touch an unrelated class's speed the way a text search would. gd_diagnostics surfaces type errors without running the game.
• Multiplayer scaffolding — mp_add_spawner / mp_add_synchronizer build Godot 4's replication nodes (including the SceneReplicationConfig sub-resource that makes them tedious by hand), mp_wire_rpc writes correctly-annotated @rpc methods, and mp_scaffold_lobby generates the host/join plumbing.
• C#, honestly — create_csharp_script scaffolds the boilerplate, and csharp_status tells you up front whether C# can work here at all. The standard Godot build has no C# support: a .cs file saves fine, attaches to nothing, and fails silently. Better to find that out before writing any.
• Preset toolsets at startup — GODOT_MCP_TOOLSETS=runtime,debug (or all) puts those tools in the FIRST tool list. Enabling one mid-session relies on the client re-fetching list_tools, and several clients cache it for the session; presetting sidesteps that entirely.
• Opt-in confirmation gate — set GODOT_MCP_REQUIRE_CONFIRM=true and operations with no undo path (file deletes/renames, script rewrites, mass renames, project settings) require an explicit confirm: true. Edits to an open scene are exempt — those do land on Godot's undo history, so Ctrl+Z (or undo_last) already covers them.
• Pre-flight validation — validate_scripts sweeps every .gd (loading each the way the editor does, so a script using an autoload isn't reported as broken); validate_scene_integrity flags nodes left with an empty required resource — including an instance whose script went missing, which otherwise just stops behaving with no error; validate_meshes catches empty geometry.
• Look at a scene without running it — render_scene_preview renders a 2D scene to a PNG offscreen, auto-framed on its content. Checking whether a level's platforms line up used to mean launching the game; now it doesn't, so it actually gets checked.
• Says when a write didn't land — a property can exist, accept an assignment and still hold something else (Godot clamps and coerces silently: a TextureRect asked for size.y = 6.667 keeps 16). Scene tools read back what they wrote and report the mismatch instead of reporting success.
• Wires exported node slots — set_node_reference points an @export var target: Area2D at another node, the thing you'd otherwise do by dragging in the inspector and which no value-based property tool can express.

---

⚙️ Running more than one project

One project on one machine needs no configuration. If you run several — or a CI editor alongside your own — set two things, because the addon dials a fixed port and cannot tell which server answered:

| Variable | Where | What it does | |---|---|---| | GODOT_MCP_PORT | server and editor | Port for the bridge. Give each project its own. | | godot_mcp/network/port | Project Settings | Per-project port, if you'd rather not set an env var on the editor. GODOT_MCP_PORT overrides it. | | GODOT_MCP_PROJECT | server | Absolute path of the project this server serves. Any editor with a different project open is refused. |

GODOT_MCP_PROJECT is the one worth setting even with a single project. Without it the first editor to reach the port is trusted with every tool call, so an unrelated editor that happens to be open can end up receiving edits meant for this one. With it, that connection is refused and the editor says so i