{ "markdown": "
\n\n\"godot-mcp-bridge\"\n\n# godot-mcp-bridge\n\n**An AI that works *with* you in the Godot editor โ€” not instead of you.**\n\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)\n[![Godot 4.5+](https://img.shields.io/badge/Godot-4.5%2B-478CBF?logo=godotengine&logoColor=white)](https://godotengine.org)\n[![231 tools](https://img.shields.io/badge/tools-231-brightgreen)](#-what-can-it-do)\n[![Last commit](https://img.shields.io/github/last-commit/TomasLucasUTN/godot-mcp-bridge)](https://github.com/TomasLucasUTN/godot-mcp-bridge/commits/main)\n[![Stars](https://img.shields.io/github/stars/TomasLucasUTN/godot-mcp-bridge?style=social)](https://github.com/TomasLucasUTN/godot-mcp-bridge/stargazers)\n\n
\n\nEvery Godot MCP server lets an AI drive the editor. **This one also tells the AI what\n*you* just did** โ€” the scene you opened, the node you selected, the file you saved โ€”\nso you can both work in the same project at the same time without stepping on each\nother. Add a real step-debugger, scope-aware refactoring through Godot's language\nserver, live-tree edits that never clobber your unsaved work, and 231 tools that were\neach verified against a running editor rather than just written.\n\nStarted as a fork of [tomyud1/godot-mcp](https://github.com/tomyud1/godot-mcp) (MIT\nlicensed) and has since diverged substantially โ€” see [`CHANGELOG.md`](./CHANGELOG.md).\n\n---\n\n## ๐Ÿ’ฌ What you'd actually say to it\n\n> *\"The player falls through the floor sometimes. Set a breakpoint in\n> `_physics_process` and tell me what `velocity` is when it happens.\"*\n\n> *\"Build me an enemy: CharacterBody2D, circle collider, sprite, patrol script,\n> and put it in the `enemies` group.\"*\n\n> *\"Run the game, press jump, screenshot it, and tell me if the animation played.\"*\n\n> *\"Which of my resources aren't referenced by anything anymore?\"*\n\n> *\"Export a Windows debug build and tell me when it's done.\"*\n\nUnder the hood that's a breakpoint hit read from a paused frame, a scaffolded scene\ntree, a runtime input + screenshot loop, a dependency sweep, and an async headless\nbuild โ€” but you don't have to know which tool does which.\n\n
\nWhat a debug session actually returns\n\n```jsonc\n// debug_launch({scene: \"res://scenes/level.tscn\"})\n{ \"state\": \"stopped\", \"stopped_reason\": \"breakpoint\", \"hit_breakpoint\": true }\n\n// debug_stack_trace()\n{ \"frames\": [{ \"name\": \"_physics_process\", \"line\": 17,\n \"source\": \".../scenes/player.gd\" }] }\n\n// debug_variables({variables_reference: 1}) โ† the Locals scope\n{ \"variables\": [{ \"name\": \"delta\", \"value\": \"0.01666666666667\" },\n { \"name\": \"direction\", \"value\": \"\" }] }\n\n// debug_evaluate({expression: \"velocity\"})\n{ \"result\": \"(0.0, 0.0)\" }\n```\n\nReal output from the test project โ€” `delta` is exactly 1/60, matching its 60 Hz\nphysics tick.\n
\n\n---\n\n## โœจ Why this one\n\n**It's bidirectional.** The AI can poll `get_editor_activity` to see what *you* just did\nin the editor โ€” selection, scene open/close/save, script focus, resource saves, asset\nreimports, undo/redo, which screen you're on โ€” tagged human vs its own actions. It finds\nout you moved something without having to ask. Every other Godot MCP is one-directional:\nthe AI drives, and is blind to you. (Checked by reading the source of 12 competing\nservers in July 2026, not their READMEs.)\n\n**It doesn't clobber your work.** Many Godot MCP servers edit your `.tscn` files on disk.\nIf you have that scene open with unsaved changes, they silently overwrite it. Here, when\na scene is open, every mutating tool edits the **live editor tree** instead โ€” your\nunsaved edits survive and every change goes through Godot's **undo system** (Ctrl+Z\nworks). Closed scenes still edit on disk as usual.\n\n**The claims are tested, not asserted.** 526 GDScript checks against the tool handlers,\n147 Node tests for the bridge and the tool registry, and 43 that drive a **real Godot\neditor** โ€” creating scenes, mutating one that is open, launching an actual game โ€” on\nevery push, on both Godot 4.5 and 4.7. Every one of the tools that writes to your project\nhas automated coverage.\n\nThat suite is not decoration; it is where the bugs came from. It caught `close_scene_tab`\nbeing broken on 4.5 (the minimum this README promises), a `run_scene` that froze the\nwhole editor for its entire timeout on every single call, and a `res://` texture path\nthat five different tools accepted and silently threw away. Each of those was found by a\ntest that failed, not by reading the code โ€” and each is in\n[`CHANGELOG.md`](./CHANGELOG.md) with what it cost.\n\nSee [Limitations](#-limitations) for what it still can't do.\n\nMore of what it does:\n\n- **Step-debugger** โ€” set breakpoints, step, read the real call stack and frame variables,\n evaluate expressions in the paused frame, over Godot's own Debug Adapter. Stop at the\n failure and look at actual values instead of inferring them from `print()` output.\n- **Real headless export** โ€” builds an actual game binary via a shadow-workspace clone,\n asynchronously, without freezing the editor (`export_project` โ†’ `get_export_status`).\n- **Runs your real tests** โ€” `run_gut_tests` executes your GUT unit suite (sync or async)\n and reports pass/fail, so the AI acts on real results instead of guessing.\n- **Drives the running game** โ€” call methods, set properties, `await` signals, `game_eval`\n a snippet, record/replay input, snapshot the live tree, even a multiplayer peer-spawn\n harness (`spawn_headless_peers`) โ€” deterministic playtesting without screenshots.\n- **Sandboxed paths** โ€” every path is guarded against traversal outside the project\n (the class of bug behind CVE-2026-15522 in another server).\n- **Writes the boilerplate for you** โ€” `wire_signal` connects a signal *and* generates\n the correctly-typed handler; `generate_onready_refs` emits typed `@onready` vars for a\n subtree; `scaffold_entity` builds a character (body + collision shape resource + sprite\n + movement script) in one call; `scaffold_state_machine` lays out a working FSM.\n Physics layers can be set **by name** instead of bit indices.\n- **Tells you what's rotting** โ€” `find_unused_resources`, `detect_circular_dependencies`,\n `analyze_scene_complexity`, and `analyze_signal_flow` (which catches connections whose\n handler doesn't exist โ€” a bug that otherwise only shows up at runtime).\n- **Asks what changed, not for everything again** โ€” `scene_diff` takes a snapshot id\n and then returns only the added, removed and modified nodes (with before/after\n values), so the agent stops paying for a full `read_scene` every time it looks back.\n It catches your edits too, not just its own.\n- **Catches multiplayer bugs that fail silently** โ€” `mp_diagnose` flags an `.rpc()`\n call to a method with no `@rpc` annotation, a synchronizer replicating nothing, and\n a spawner whose `spawn_path` goes nowhere. None of those error when you write them;\n all of them look like \"the client is broken\" when a second peer joins.\n- **Visual regression** โ€” `compare_screenshots` diffs two frames and reports the changed\n percentage and region, so \"did my change actually alter the screen?\" has an answer.\n- **Tests your UI like a human would** โ€” click a button by its visible caption\n (`click_control_runtime({text: \"Start\"})`, which refuses and lists candidates if the\n text is ambiguous), then assert what's on screen with `assert_screen_text` โ€” reading the\n live Control tree, so it works headless with no OCR.\n- **Localization that doesn't half-work** โ€” `sync_localization` registers the\n `.translation` files Godot generated from your CSV (the manual step that silently makes\n a language never load) and reports every key you haven't translated yet, per locale.\n- **Setup that explains itself** โ€” `npx godot-mcp-bridge install` installs and enables the\n addon in one command; `doctor` diagnoses a broken setup; `diagnose_connection` tells the\n AI exactly why the editor isn't connecting.\n- **Fast + robust** โ€” `batch_execute` / `batch_scene_edit` cut N calls to one; heavy reads\n (`read_scene`, `scene_tree_dump`, `classdb_query`) take `max_depth`/`filter` to stay\n token-cheap; only 37 tools load by default so the agent stays focused. **Measured, not\n claimed** โ€” see below.\n- **Symbol-accurate refactoring** โ€” `gd_rename` and `gd_references` go through Godot's\n language server, so they understand scope: renaming a local `speed` won't touch an\n unrelated class's `speed` the way a text search would. `gd_diagnostics` surfaces type\n errors without running the game.\n- **Multiplayer scaffolding** โ€” `mp_add_spawner` / `mp_add_synchronizer` build Godot 4's\n replication nodes (including the `SceneReplicationConfig` sub-resource that makes them\n tedious by hand), `mp_wire_rpc` writes correctly-annotated `@rpc` methods, and\n `mp_scaffold_lobby` generates the host/join plumbing.\n- **C#, honestly** โ€” `create_csharp_script` scaffolds the boilerplate, and `csharp_status`\n tells you up front whether C# can work here at all. The standard Godot build has no C#\n support: a `.cs` file saves fine, attaches to nothing, and fails silently. Better to\n find that out before writing any.\n- **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.\n- **Opt-in confirmation gate** โ€” set `GODOT_MCP_REQUIRE_CONFIRM=true` and operations with\n no undo path (file deletes/renames, script rewrites, mass renames, project settings)\n require an explicit `confirm: true`. Edits to an **open** scene are exempt โ€” those do\n land on Godot's undo history, so Ctrl+Z (or `undo_last`) already covers them.\n- **Pre-flight validation** โ€” `validate_scripts` sweeps every `.gd` (loading each the way\n the editor does, so a script using an autoload isn't reported as broken);\n `validate_scene_integrity` flags nodes left with an empty required resource โ€” including\n an instance whose script went missing, which otherwise just stops behaving with no error;\n `validate_meshes` catches empty geometry.\n- **Look at a scene without running it** โ€” `render_scene_preview` renders a 2D scene to a\n PNG offscreen, auto-framed on its content. Checking whether a level's platforms line up\n used to mean launching the game; now it doesn't, so it actually gets checked.\n- **Says when a write didn't land** โ€” a property can exist, accept an assignment and still\n hold something else (Godot clamps and coerces silently: a `TextureRect` asked for\n `size.y = 6.667` keeps 16). Scene tools read back what they wrote and report the\n mismatch instead of reporting success.\n- **Wires exported node slots** โ€” `set_node_reference` points an `@export var target: Area2D`\n at another node, the thing you'd otherwise do by dragging in the inspector and which no\n value-based property tool can express.\n\n---\n\n## โš™๏ธ Running more than one project\n\nOne project on one machine needs no configuration. If you run several โ€” or a CI\neditor alongside your own โ€” set two things, because the addon dials a fixed port\nand cannot tell which server answered:\n\n| Variable | Where | What it does |\n|---|---|---|\n| `GODOT_MCP_PORT` | server **and** editor | Port for the bridge. Give each project its own. |\n| `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. |\n| `GODOT_MCP_PROJECT` | server | Absolute path of the project this server serves. Any editor with a different project open is refused. |\n\n`GODOT_MCP_PROJECT` is the one worth setting even with a single project. Without\nit the first editor to reach the port is trusted with every tool call, so an\nunrelated editor that happens to be open can end up receiving edits meant for\nthis one. With it, that connection is refused and the editor says so instead of\nsilently taking the work.\n\n---\n\n## ๐Ÿงฎ What it costs per request\n\nTool definitions are sent on **every** request, so a large always-on surface is a\nstanding tax on every message โ€” the most common complaint about Godot MCP servers,\nand one nobody publishes a number for. Here is ours, from\n[`scripts/measure-tools.mjs`](./mcp-server/scripts/measure-tools.mjs) so you can\nre-run it:\n\n| | tools | ~tokens |\n|---|---:|---:|\n| **What a client sees by default** | 44 | **9,533** |\n| of which: the 7 the server answers itself | 7 | 1,096 |\n| Everything, every toolset on | 238 | 50,934 |\n\nThe 44 is 37 Godot tools plus seven the server answers on its own (status,\nguides, `find_tools`, the toolset controls). They are not Godot tools, but they\nride in every request, so counting only the 38 published a number 1,100 tokens\nbelow what a request actually costs โ€” the script counts them now.\n\nSo the default surface is **18.7% of the full one**, and turning everything on\ncosts roughly **41,000 extra tokens on every request**. That is the reason the\ndefault is small and the rest is opt-in per toolset (or preset once via\n`GODOT_MCP_TOOLSETS`), rather than a judgement that the other 192 tools do not\nmatter. `find_tools` searches all 231 by what you want to do, so a tool being\nunloaded never means it is unfindable. The default grew by ~800 tokens when\npreviews (`dry_run`), subtree reads and the detached launch mode were added to\ncore tools โ€” measured rather than assumed, which is the point of publishing it.\n\nThe estimate is chars รท 4, which is close enough to compare sets and honest about\nbeing an estimate. The most expensive definitions inside `core` are\n`modify_node_property`, `add_node` and `run_scene` โ€” verbose because they carry\nthe \"use this, NOT that\" wording that stops an agent picking the wrong neighbour.\n\n---\n\n## ๐Ÿ“Š How it compares\n\nChecked in July 2026 by reading each project's **source**, not its marketing. Star count\nmostly tracks how early a project shipped, so it's listed last rather than first.\n\n| | **godot-mcp-bridge** (this repo) | [yurineko73/Godot-MCP-Native](https://github.com/yurineko73/Godot-MCP-Native) (most active) | [tomyud1/godot-mcp](https://github.com/tomyud1/godot-mcp) (fork origin) | [Coding-Solo/godot-mcp](https://github.com/Coding-Solo/godot-mcp) (most-starred) |\n|---|---|---|---|---|\n| Tools | 231 (38 loaded by default) | 155 | 42 | ~14 |\n| Live-tree editing + undo | โœ… | โœ… | โŒ (overwrites open scenes on disk) | โŒ |\n| Step-debugger | โœ… | โœ… | โŒ | โŒ |\n| Drives the running game (input, `game_eval`) | โœ… | โœ… | โŒ | โŒ |\n| **Sees what *you* just did** (`get_editor_activity`) | โœ… | โŒ | โŒ | โŒ |\n| Async headless export (doesn't block the editor) | โœ… | CLI export | โŒ | โŒ |\n| Runs your real test suite (GUT) | โœ… | โŒ | โŒ | โŒ |\n| Works with Codex CLI (stdio) | โœ… | โŒ (HTTP only โ€” their issues #1, #24) | โœ… | โœ… |\n| Last release | active | active | Apr 2026 | Apr 2026 |\n| GitHub stars | โ€” | 464 | 397 | 4.9k |\n\n**About the Node process.** `Godot-MCP-Native` runs entirely inside the editor and\nsells that as \"no sidecar\". It is a real trade, so here is the other half of it. A\nserver living in the editor process is bound to the editor's lifetime *and* to its\nmain thread. That costs three things: it cannot be spawned over **stdio**, so\nstdio-only clients like Codex CLI cannot load it at all; it **dies when Godot\ncrashes**, taking your AI client's connection with it; and any slow work **freezes\nthe editor**, because `@tool` scripts run on the main thread.\n\nThat last one is measurable. Asked \"which assets does nothing reference?\" on a\nproject with a couple of free asset packs in it (24,649 files, 12,201 images), the\nsame analysis takes **1.6 seconds** in a separate process and never touches the\neditor โ€” where an in-editor implementation blocks the UI for **26 seconds**. The\nsidecar is an install step you pay once; the main thread is one you pay every call.\n\nThe honest read: undo, a debugger, and runtime control are table stakes now โ€” the good\nprojects all have them. What no one else does is the bidirectional half, and the two\nmost-starred options haven't shipped since April.\n\n---\n\n## ๐Ÿ“ฆ Quick Start\n\n### 0. Install Node.js (one-time setup)\n\nDownload and run the installer from **[nodejs.org](https://nodejs.org/en/download)** (LTS version). It's a standard installer โ€” no terminal needed.\n\n### 1. Install the Godot plugin\n\n**One command, from inside your Godot project folder:**\n\n```bash\nnpx godot-mcp-bridge install\n```\n\nThat copies the addon into `addons/godot_mcp/` and enables the plugin in\n`project.godot` (backing the file up first, and keeping every other plugin and\nsetting intact). Add `--client claude-desktop` or `--client cursor` and it will\nregister the server in that client's config too.\n\nSomething not connecting? Run this and it tells you which step is missing:\n\n```bash\nnpx godot-mcp-bridge doctor\n```\n\n
\nPrefer to do it by hand\n\nCopy the `addons/godot_mcp/` folder from this repo into your Godot project's\n`addons/` directory. Then go to **Project โ†’ Project Settings โ†’ Plugins** and\nenable the **Godot MCP** plugin.\n\n(The \"Godot AI Assistant tools MCP\" AssetLib listing belongs to the upstream\nproject this repo forked from, not this one โ€” installing from there gets you\nthe upstream addon, not this fork.)\n
\n\n### 2. Add the server config to your AI client\n\n**Claude Desktop** โ€” Settings โ†’ Developer โ†’ Edit Config โ†’ open the config file and paste:\n\nMac / Linux:\n```json\n{\n \"mcpServers\": {\n \"godot\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"godot-mcp-bridge\"]\n }\n }\n}\n```\n\nWindows:\n```json\n{\n \"mcpServers\": {\n \"godot\": {\n \"command\": \"cmd\",\n \"args\": [\"/c\", \"npx\", \"-y\", \"godot-mcp-bridge\"]\n }\n }\n}\n```\n\n**Cursor** โ€” Settings โ†’ MCP โ†’ Add Server:\n\nMac / Linux:\n```json\n{\n \"mcpServers\": {\n \"godot\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"godot-mcp-bridge\"]\n }\n }\n}\n```\n\nWindows:\n```json\n{\n \"mcpServers\": {\n \"godot\": {\n \"command\": \"cmd\",\n \"args\": [\"/c\", \"npx\", \"-y\", \"godot-mcp-bridge\"]\n }\n }\n}\n```\n\n**Claude Code** โ€” run in terminal:\n```bash\nclaude mcp add godot -- npx -y godot-mcp-bridge\n```\n\n**Codex CLI** โ€” run in terminal:\n```bash\ncodex mcp add godot -- npx -y godot-mcp-bridge\n```\n\nOr add it to `~/.codex/config.toml` by hand:\n```toml\n[mcp_servers.godot]\ncommand = \"npx\"\nargs = [\"-y\", \"godot-mcp-bridge\"]\n```\n\nOn Windows use `command = \"cmd\"` and `args = [\"/c\", \"npx\", \"-y\", \"godot-mcp-bridge\"]`.\n\nCodex CLI speaks stdio only โ€” it cannot use an MCP server that is reachable\nsolely over HTTP. This server is a stdio server, so it works there without a\nbearer token or a port to keep track of.\n\nWorks with any MCP-compatible client (Cline, Windsurf, etc.)\n\n### 3. Restart your AI client\n\nClose and reopen Claude Desktop / Cursor / your client so it picks up the new config.\n\n### 4. Restart your Godot project\n\nHit **Restart Project** in the Godot editor. Check the **top-right corner** โ€” you should see **MCP Connected** in green. You're ready to go.\n\n---\n\n## ๐Ÿงฐ What Can It Do?\n\n### 231 Tools, 38 Loaded by Default\n\nA big always-on tool list makes an AI agent wander between unrelated\ncapabilities and burns context on definitions it never uses. So only **`core`\n(37 tools)** is visible by default โ€” the smallest set that carries a normal\nsession end to end: look around, edit scenes and scripts, run the game, read the\nerrors.\n\nEverything else is grouped **by intent** and is one call away:\n`enable_toolset({ name: \"runtime\" })`. `list_toolsets` shows every set, what it's\nfor, and the names of the tools inside it โ€” so the AI can find what it needs\nwithout loading the whole catalog first. Nothing is ever unreachable.\n\nFor a goal-to-tool index and per-topic usage guides (scene editing patterns,\nthe runtime testing loop, asset generation, troubleshooting), see\n[`docs/TOOLS.md`](./docs/TOOLS.md) โ€” the same content the server exposes live\nvia the `get_guide` tool, in browsable form.\n\n| Toolset | Tools | What it's for |\n|---------|-------|---------|\n| **core** *(always on)* | 38 | Look around (`read_scene`, `scene_tree_dump`, `search_project`, `classdb_query`), edit scenes/nodes (live-tree + undo, `batch_scene_edit`, `set_node_reference`), scripts, run the game, **see a scene without running it** (`render_scene_preview`), read errors, `restart_editor` |\n| **runtime** | 29 | Drive the running game: input (keyboard/mouse/**gamepad/touch**), `game_eval`, live node/property access, `await_signal_runtime`, UI-by-text clicking + `assert_screen_text`, input record/replay, multiplayer + `spawn_headless_peers` |\n| **debug** | 11 | Step-debugger over Godot's own Debug Adapter: breakpoints, step over/in/out, call stack, scope variables, expression evaluation in the paused frame |\n| **code_intel** | 8 | Godot's language server: scope-aware `gd_definition`, `gd_references` and `gd_rename` (unlike text search), plus type diagnostics without running the game |\n| **scene_editing** | 14 | Deeper scene work: collision shapes, sprites/meshes/materials, groups, anchors, spatial queries |\n| **project_config** | 13 | Project settings, input map, autoloads, resources, `sync_localization` |\n| **animation** | 14 | AnimationPlayer tracks/keyframes, AnimationTree state machines |\n| **editor** | 14 | The editor itself: `get_editor_activity` (what *you* just did), selection, scene tabs, performance |\n| **physics** | 7 | Collision shapes, raycasts, layers **by name**, collision presets |\n| **tilemap** | 8 | TileMapLayer cell painting, terrain + deterministic bitwise autotiling |\n| **analysis** | 9 | `scene_diff` (what changed since you last looked, without re-reading the tree), `mp_diagnose` (silent multiplayer bugs), `find_unused_resources`, `detect_circular_dependencies`, `analyze_scene_complexity`, `analyze_signal_flow`, `get_project_statistics`, `compare_screenshots` |\n| **scaffolding** | 12 | `wire_signal`, `generate_onready_refs`, `scaffold_entity`, `scaffold_state_machine`, `create_csharp_script`, plus multiplayer: `mp_add_spawner`, `mp_add_synchronizer`, `mp_wire_rpc`, `mp_scaffold_lobby` |\n| **testing** | 6 | GUT test runner (sync/async), scene/mesh integrity validation, assertions |\n| **ui** | 6 | Theme resources, colors, stylebox overrides |\n| **3d** | 9 | Mesh instances, lighting presets, materials, environment, cameras, gridmaps |\n| **shaders** | 6 | Create/read/edit GDShader, assign materials, set params |\n| **navigation** | 5 | NavigationRegion setup, mesh baking, agents, layers |\n| **vfx** | 5 | GPUParticles2D/3D, gradients, presets |\n| **refactor** | 5 | Project-wide symbol rename, bulk property edits, file moves |\n| **export** | 4 | Export presets and async export jobs |\n| **audio** | 3 | AudioStreamPlayer variants, buses |\n| **utility** | 2 | 2D asset generation, project/scene visualizer |\n\n### Interactive Visualizer\n\nRun `map_project` and get a browser-based explorer at `localhost:6510`:\n- Force-directed graph of all scripts and their relationships\n- Click any script to see variables, functions, signals, and connections\n- Edit code directly in the visualizer โ€” changes sync to Godot in real time\n- Scene view with node property editing\n- Find usages before refactoring\n\n![Interactive project visualizer](./screenshots/visualizer-preview.png)\n\n---\n\n## ๐Ÿ—๏ธ Architecture\n\n```\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” MCP (stdio) โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” WebSocket โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ AI Client โ”‚โ—„โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ–บโ”‚ MCP Server โ”‚โ—„โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ–บโ”‚ Godot Editor โ”‚\nโ”‚ (Claude, โ”‚ โ”‚ (Node.js) โ”‚ port 6505 โ”‚ (Plugin) โ”‚\nโ”‚ Cursor) โ”‚ โ”‚ โ”‚ โ”‚ โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ Visualizer โ”‚ โ”‚ 230 tool โ”‚\n โ”‚ HTTP :6510 โ”‚ โ”‚ handlers โ”‚\n โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚\n โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ–ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\n โ”‚ Browser โ”‚\n โ”‚ Visualizer โ”‚\n โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n```\n\n---\n\n## โš ๏ธ Limitations\n\nWritten to be the section you read *before* hitting these, not after.\n\n**Requires a running editor.** This drives a live Godot instance over a WebSocket; it\nis not a headless CLI. No editor open, no tools. Godot **4.5 or newer** โ€” 4.3 and 4.4\nwere measured against the live suite and the editor-mode scene path does not work there.\n\n**Local only, one editor at a time.** Port 6505 on localhost, first come first served.\nTwo projects open at once means the second one loses; set `GODOT_MCP_PORT` on both the\nserver and the addon, or `GODOT_MCP_PROJECT` so the bridge refuses the wrong project\ninstead of silently driving it.\n\n**A closed scene is edited on disk, with no undo entry.** When the scene is *open*\neverything goes through Godot's undo history and Ctrl+Z works, including over a whole\n`batch_scene_edit`. When it is closed there is no history to write to โ€” use version\ncontrol. Many destructive tools take `dry_run: true` to preview first.\n\n**Enabling a toolset mid-session may not reach your client.** Only `core` (37 tools) is\non by default. `enable_toolset` flips it server-side and the server does send\n`notifications/tools/list_changed`, but several clients cache the tool list for the\nwhole session and never re-fetch โ€” and then the newly enabled tools stay invisible until\nyou restart the client. If you know you want them, set\n`GODOT_MCP_TOOLSETS=runtime,debug` (or `all`) so they are in the *first* list.\n\n**`game_eval` runs your snippet inside the running game.** Code that does not compile is\ncaught in the editor before the game ever sees it. A snippet that fails at *runtime* โ€”\ndereferencing a freed node, calling a method that does not exist โ€” halts the game under\nthe editor's attached debugger, and the call times out instead of returning an error.\nThat is the debugger, not the bridge: launch with `run_scene({attach_debugger: false})`\nand the same bad snippet comes back as a result in ~18ms with the connection intact\n(measured). The trade is stated in the tool description โ€” no step-debugging, and\n`get_errors` loses its Debugger>Errors source.\n\n### What has been measured, and when\n\nNumbers rather than adjectives, all from 2026-09-03 against a 24,880-file project:\n\n| | |\n|---|---|\n| Default tool surface | 44 tools, **9,533 tokens** of schema (everything on: 238 / 50,934) |\n| Slowest read-only tool | `get_project_statistics` at **2,012 ms** โ€” it answers in the MCP server; the in-editor version took 120,685 ms |\n| Largest answer | `map_project` at **7,744 chars** โ€” it used to return 151,159 |\n| Runtime helper connect | **1.6-1.7 s**, attached or detached |\n| `game_eval` runtime error, detached | **18 ms**, connection survives |\n| Mutating tools pointed at a target that cannot exist | 70 editor-side + 11 runtime, **none reports success** |\n| Path-traversal attempts against the sandbox | 16 refused, 11 odd-but-contained inputs checked by where they resolve, **zero escapes** |\n| Tests | 243 Node unit, 44 live against a real editor, 786 GDScript โ€” green on Godot 4.5 and 4.7 |\n\nEvery one of those is re-runnable: `mcp-server/scripts/measure-tools.mjs` for the\nschema cost, `scripts/measure-runtime-cost.gd` for per-tool time and payload, and the\nrest are assertions in the suites.\n\n**C# is scaffolding only.** `create_csharp_script` writes a correctly-shaped file and\n`csharp_status` tells you honestly whether this editor can run C# at all (a standard,\nnon-Mono build cannot). The language-server and debugger tools cover GDScript, not C#.\nThe blocker is upstream: Godot has no non-interactive way to generate the `.csproj`,\nverified across four CI runs.\n\n**The AI still does not know Godot as well as you do.** It struggles with complex UI\nlayouts, compositing scenes, and some property manipulation. It cannot build a game on\nits own โ€” it debugs, writes scripts, runs and inspects the thing, and keeps you company\nwhile you do. Feedback welcome.\n\n---\n\n## ๐Ÿ”ง Development\n\nTo build from source instead of using npm:\n\n```bash\ncd mcp-server\nnpm install\nnpm run build\n```\n\nThen point your AI client at `mcp-server/dist/index.js` instead of using `npx`.\n\n---\n\n## ๐Ÿ“– Release notes\n\nNarrative write-ups of each release live in [`release-notes/`](./release-notes/) โ€” latest is [v1.2.1](./release-notes/v1.2.1.md). For the full change history, see [`CHANGELOG.md`](./CHANGELOG.md).\n\n---\n\n## ๐Ÿค Contributing\n\nSee [`CONTRIBUTING.md`](./CONTRIBUTING.md). Security issues: see [`SECURITY.md`](./SECURITY.md) instead of opening a public issue.\n\n---\n\n## ๐Ÿ“„ License\n\nMIT\n\n---\n\n**[Report Issues](https://github.com/TomasLucasUTN/godot-mcp-bridge/issues)**\n", "bytes": 28735, "sha": "5a12a90d0e669673a9795bf2e10b3593d3f8bb5c496b85858f6247d422016b86", "repo_slug": "tomaslucasutn/godot-mcp-bridge", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_tomaslucasutn_godot_mcp_bridge_e17ba10a/readme" }