Godot Breakpoint

A Model Context Protocol server that brings the Godot game engine into an AI assistant's development loop — authoring scenes, writing type-checked GDScript, running the project, and debugging the live game. Developed and tested with Claude; MCP is an open protocol, so other clients can connect too (see Compatibility).

npm 1.87.0 · addon 1.17.0 · full 293 / secure-default 280 tools · 6 MCP resources · MIT. The host builds against the stable @modelcontextprotocol/sdk 1.x API and is exercised by a 1000-test suite plus real-Godot integration jobs on Node 18/20/22.

Breakpoint MCP connects an MCP-compatible AI assistant to a running Godot editor and game. Instead of only scaffolding files, the assistant can open a scene, add and wire nodes with full undo/redo, write GDScript with type-aware completion and diagnostics, set a breakpoint and step through a failure from real program state, and then drive the running game — the same inner loop a human developer uses.

It speaks Godot's own protocols — the editor plugin's loopback bridge, and Godot's built-in language server (LSP) and debug adapter (DAP) — rather than reimplementing them, so behavior tracks the engine you already have.

Why Breakpoint?

Breakpoint is an MCP server that drives Godot through the engine's own interfaces: the editor plugin's loopback bridge for scene/node/resource work, a runtime bridge inside the running game, the headless CLI, and — the part that sets it apart — Godot's built-in language server (LSP) and debug adapter (DAP), to which Breakpoint speaks as a real client. Most Godot MCP servers stop at the first group: they create and edit scenes and scripts, take screenshots, and read the output log. Several now add stepping too — but they drive Godot's internal editor debugger and present it in "DAP-style" shapes rather than speaking the Debug Adapter and language-server protocols as a client. Breakpoint is that client, for GDScript and C#, and its breakpoints are proven to stop execution by integration tests run against real Godot binaries in CI. That is the difference between observing a running game from the outside and stopping inside it at real program state.

Two differentiating capabilities are the reason to reach for Breakpoint:

• A step-debugger for GDScript and C#. Set a breakpoint, step, read the real call stack and variable values, watch expressions, and evaluate in the paused frame — over Godot's Debug Adapter (and netcoredbg for C#). This is the difference between inspecting state and reading logs: the assistant can stop at the failure and look at actual values instead of inferring them from print() output and re-runs. A runnable example lives in example/demo/: a buggy melting-snowman scene where the debugger stops on ice -= melt and reveals melt = -2 — a mild warm spell growing the ice instead of melting it. The same bug is mirrored in C# at example-csharp/demo/ (DemoSnowman.ApplyWarmth), diagnosed the same way over netcoredbg — and verified the same way on both tracks: the read-only assertion family below proves the one-line clamp over the runtime bridge (GrewEver == false, "ALL MELTED" on screen), a check that fails before the fix and passes after.
• A language-server client for GDScript and C#. Completion, hover, go-to-definition, find references, rename, and diagnostics — over Godot's LSP (and OmniSharp for C#). Edits are symbol-accurate rather than text-substituted, and type errors surface before the project runs.

Around those, the editing surface is built to be safe to hand to an agent: every edit goes through EditorUndoRedoManager (Ctrl-Z reverts anything the assistant did), destructive tools are confirmation-gated, and every tool result is validated against a frozen output schema. A read-only verification family (assert node state, scene structure, on-screen text, performance baselines, and screenshot diffs) lets the assistant check a running game the way a test would — and because the same server also debugs, a failed assertion is one step from the state that caused it. The editor, LSP, DAP, and runtime bridges are exercised together against a real headless Godot in CI.

It is also secure by default, which is unusual in this field — and the mechanism matters more than the label. A per-project shared secret authenticates every bridge (constant-time, minted into the git-ignored res://.godot/), every socket binds to loopback only, and the highest-blast tools — arbitrary code execution and network egress — are dropped at registration, not merely flagged. They are absent from tools/list until you opt in, so the default surface is 280 tools an agent can actually call, not 293 with a warning label on 13 of them. Destructive operations are confirmation-gated and fail closed on clients that cannot prompt. Nothing runs in the cloud and no project data leaves the machine.

Every tool also publishes MCP risk annotations (readOnlyHint / destructiveHint / idempotentHint / openWorldHint), and breakpoint-mcp tools --json exports the whole surface — so what the server can do, and how risky each tool is, is checkable without running it or guessing from tool names.

When Breakpoint is the right tool — and when it isn't

It earns its keep on work that needs program state or real symbols:

• Diagnosing a live failure — a wrong value, a null reference, a crash in a signal handler: breakpoint, step, and read the actual variables in the paused frame instead of instrumenting with prints and re-running.
• Refactoring against real symbols — rename a method or property project-wide, or find every reference, over the LSP, so it's accurate rather than a text search.
• Type-aware authoring — write GDScript or C# with completion and diagnostics, catching type errors before the game runs.
• C#/.NET projects — the LSP and DAP paths cover C# as well as GDScript.
• Verifying a running game in a loop — assert node/scene/screen/performance state after a change, with a failed assertion one step from the debugger.

If you only need scene and script edits from inside the editor — scaffolding a scene, generating a script from a prompt, quick one-shot changes — there are other good alternatives to Breakpoint available in the Godot Asset Library. Breakpoint's value shows up when you need to step through a bug, refactor against real symbols, or work in C#.

How it compares

The field has many capable Godot MCP servers, and it is growing quickly — most cluster on authoring. Breakpoint is deliberately different on the axes that need real program state, real symbols, and a surface that is safe to hand an agent by default:

Capability	A typical Godot MCP server	Breakpoint
Author scenes / scripts, screenshots, read logs	✅	✅
Step-debugger (breakpoints, stack, variables, watch)	Some — via Godot's internal editor debugger	✅ real DAP client; breakpoints proven to stop in CI
C# step-debugging	✗	✅ over netcoredbg
Language-server client (completion, rename, references)	Rare	✅ GDScript and C#
Runtime verification (assert node/scene/screen/perf, golden-image diff)	✗	✅ runtime_assert_* + runtime_screenshot_diff
Deterministic playtesting (freeze time, step exact frames, seed RNG, state digest)	✗	✅ frame-exact, verified on 4.3/4.5/4.7
Arbitrary code execution in the default surface	Usually present and callable	✅ absent — dropped at registration until opted in
Published risk annotations + machine-readable tool export	✗	✅ all 293 tools, CI-enforced
Undo-safe + schema-frozen results	Rare	✅ every mutation

This describes capability classes, not specific projects. Several servers are strong at authoring, some are actively adding debuggers, and if authoring is all you need there are good alternatives in the Asset Library. The tool count is not the axis — ours is 293 because that is what a static contract check asserts, and every one is schema-frozen and annotated.

What the tool surface costs, measured

Breadth is not free, and the honest way to offer it is to publish the bill. These are live measurements of what a tools/list response weighs — produced by host/scripts/token-cost.mjs against the running server, not estimates, and not figures quoted from anyone's README.

What an untouched install advertises is the secure-default surface of 280 tools; opting every higher-trust group in loads the full 293. Two numbers per row, because they are different bills: what the client downloads (tools/list on the wire), and what the model reads — a client hands Claude each tool's name, description and input schema and nothing else.

	Bytes on the wire	What the model reads
Breakpoint, as installed (280 tools)	353,591	208,700
Breakpoint, every group opted in (293 tools)	373,677	221,780
An authoring-focused server we re-measured (319 tools)	202,327	196,585

The second column is measured, not assumed: we captured the request Claude Code 2.1.201 actually builds with Breakpoint attached (pointed at a local capture server; nothing was sent anywhere). Every one of the 280 tools arrived as name, description and input schema — no output schema, no risk annotation, no title. So the weight that sets Breakpoint apart on the wire — a frozen outputSchema and a published risk annotation on every tool, which is what lets a client validate a result and lets you audit the surface before you trust it — costs the model's context nothing. Per tool, what Claude reads is about 1.2× the leanest alternative we have measured.

In Claude Code, the upfront bill is smaller still. Its default MCP tool search sends only tool names until the model asks for a tool, so a session pays roughly 10 KB for the whole surface and about three-quarters of a kilobyte for each tool it actually loads. The full model-read column is what a client without tool search pays upfront.

And you almost never pay the full bill. Toolsets load only the planes you asked for, so a session that just needs the debugger pays for the debugger — a measured ~86–98% upfront reduction, and it is one environment variable:

BREAKPOINT_TOOLSETS=c        # the runtime plane alone
BREAKPOINT_TOOLSETS=a,b      # editor + CLI

The byte counts are exact (≈ tokens at ~3.6 bytes/token, an estimate). Re-derive any row with node host/scripts/token-cost.mjs --summary — it prints both columns — or point it at any other stdio MCP server with --server <cmd> and compare for yourself.

Why a Node host?

Breakpoint runs a small Node process on purpose: it is what lets the server act as a real LSP and DAP client (the two capabilities above), run long jobs on the MCP task model, and connect from any stdio MCP client. The host is the price of the debugger and the language server, not incidental plumbing. Setup is one command to install and one to verify:

npx breakpoint-mcp init     # copies + enables the addon and writes your MCP-client config
npx breakpoint-mcp doctor   # verifies the Godot binary and all four bridges are live
npx breakpoint-mcp --version  # the installed version — quote this in a bug report

If you never step through a bug or refactor against real symbols, you may not need the host; if you do, that is exactly what it buys.

What it does

Breakpoint MCP is organized into four capability planes (full 293 tools, or 280 with the privileged capability group off by default — see Safety & trust model — plus 6 resources):

• Plane A — Live Editor Bridge (toolset a → 148 tools: editor_*, scene_*, node_*, signal_*, resource_*, filesystem_*, anim_*, and more): a Godot EditorPlugin opens a loopback server the host drives for scene/node/resource CRUD with full undo/redo, project settings, ClassDB introspection, selection, main-screen tab control, and editor screenshots. A read-only documentation / code-lookup family (class_reference, docs_search) is part of that 148. Four sibling toolsets ride the same bridge and are counted separately — native multiplayer authoring (netcode → 7), backend-SDK integration scaffolding (backend → 5, including leaderboard_scaffold, cloudsave_scaffold and auth_scaffold), AI asset generation (assetgen → 7), and card/board/piece authoring (tabletop → 14) — so a,netcode,backend,assetgen,tabletop → 181 tools require the editor open, not the 148 alone.

• Plane B — Headless CLI & host-side tools (godot_*, vcs_*, project search): launch the editor, run the project, export, import, and run headless scripts or tests — no editor window required. Long-running jobs (godot_export, godot_import, godot_run_headless_script) run on the formal MCP task model (create → poll → await → cancel), while simpler clients still get a blocking result. godot_run_managed / godot_output capture the game's full console. Version control (vcs_*) reads the project's git repository (status, log, diff, show, branches, blame) and performs safe local git actions (stage, commit, restore, stash, branch, switch) — destructive ops are confirmation-gated, and no network operations are exposed (push/pull stay manual).

• Plane C — Runtime Bridge (runtime_*): an autoload (BreakpointRuntimeBridge) the plugin registers into every run opens a loopback server inside the running game — live SceneTree, runtime property get/set, method calls, signal emission, input injection for play-testing, performance monitors, and in-game frame capture — plus a read-only verification family (runtime_assert_* and runtime_screenshot_diff) for checking node state, scene structure, on-screen text, performance baselines, and screenshot diffs against a running game. On Godot 4.5+ it also captures the game's console (print(), warnings, errors) with zero configuration.

• Plane D — Semantic & Debugging (gd_*, dbg_*, plus C# cs_* / cs_dbg_*): the host connects as a client to Godot's built-in GDScript language server (port 6005) and debug adapter (port 6006) — completion, hover, definition/references, rename, symbols, signature help, diagnostics, plus real debugging: breakpoints, stepping, stack/scopes/variables, watch expressions, and expression evaluation. A parallel C# plane speaks OmniSharp (LSP) and netcoredbg (DAP). Capabilities are feature-detected per engine build and degrade to a clear "unsupported" message rather than erroring.

Six MCP resources (godot://scene-tree, godot://editor-state, godot://runtime/tree, godot://runtime/log, godot://class/{name}, and the always-on godot://capabilities) expose pull-on-demand context, and clients can subscribe to be pushed updates when the editor selection, edited scene, or the live SceneTree changes.

Highlights

• Undo-safe by construction. Every edit-time mutation is wrapped in EditorUndoRedoManager — Ctrl-Z reverts anything the assistant did.
• Confirmation-gated destructive tools. Anything that deletes, overwrites, or writes a file prompts for confirmation first (with a confirm: true override, and a safe block when the client can't prompt).
• Enforced output schemas. Tool results are validated against frozen output schemas.
• Local by design. All planes talk to 127.0.0.1; screenshots render real frames.

┌───────────────────── Claude (Code / Desktop) ─────────────────────┐
│                        MCP over stdio                              │
└─────────────────────────────┬──────────────────────────────────────┘
                      host/ (TypeScript MCP server)
   ┌────────────┬──────────────┬──────────────┬────────────┬───────────┐
 spawn CLI   TCP :9080      TCP :9081       TCP :6005    TCP :6006
 (headless)  editor addon   in-game         Godot LSP    Godot DAP
             scenes/nodes   autoload        completion,  breakpoints,
             /undo          live SceneTree  diagnostics  stepping, eval
                            /monitors/input

Requirements

• Node ≥ 18 (for the host).
• Godot 4.2+ for the editor addon (4.4+ recommended). A few runtime features use Godot 4.5+, and some language-server / debug-adapter capabilities light up on newer builds as the engine implements them.

Installation

Quick start (recommended)

From your Godot project folder, one command installs and enables the editor addon and prints your MCP-client config:

npx breakpoint-mcp init

Then open the project in Godot and verify everything is wired up:

npx breakpoint-mcp doctor

If the project was already open in Godot when you ran init, reopen it. init enables the plugin by writing [editor_plugins] into project.godot, and Godot reads that file at project load — it does not hot-reload it. An editor that was already running keeps the plugin disabled, the editor bridge never starts, and doctor --require-live reports it as down. Closing the project and opening it again is the fix.

init copies the addon into addons/breakpoint_mcp/, enables it in project.godot, and prints the client config snippet — pass --client claude-desktop|cursor|windsurf|vscode to write it into that client's config directly, or --client claude-code to get the claude mcp add command. By default init installs the addon bundled in the package; add --from-github [ref] to fetch it from GitHub instead (e.g. --from-github main for the latest, or a tag like --from-github v1.3.0; --repo <owner/repo> targets a fork). doctor checks the Godot binary, the addon, and the four bridges (add --require-live once the editor is open to require the three the editor brings up, or --require-live=all to also require the runtime bridge, which only exists while the game is running; --json for a machine-readable report). The manual steps below do the same thing by hand.

1. Install the editor addon (manual)

These by-hand steps are for working from a checkout of this repository, or if you would rather do it yourself. If you installed from npm, npx breakpoint-mcp init does all of this for you — the addon ships bundled in the package, so you don't need the repository.

Copy addons/breakpoint_mcp/ into your project's addons/ folder, then enable it under Project → Project Settings → Plugins → Breakpoint MCP. On enable it listens on 127.0.0.1:9080 (override with BREAKPOINT_BRIDGE_PORT before launching Godot).

Enabling the plugin also auto-registers the runtime autoload (BreakpointRuntimeBridge), so the runtime_* tools work as soon as the project runs (it listens on 127.0.0.1:9081 inside the game). No manual autoload setup needed. The autoload ships in your exports too, and there it stays closed: only a game started by an editor build opens the port (details).

Once enabled, a Breakpoint MCP dock appears on the right-hand side of the editor. It shows the live health of all four bridges (editor / runtime / GDScript LSP / DAP), the configured ports and project path, and a one-click Copy MCP-client config button — the in-editor twin of doctor + init. It is status/config only: the assistant still runs in your MCP client, not in the editor.

Godot's language server (port 6005) and debug adapter (port 6006) are built in and enabled by default while the editor is open — the gd_* and dbg_* tools use them directly, no addon required. Ports are configurable under Editor → Editor Settings → Network → Language Server / Debug Adapter.

2. Get the host

The host is published to npm as breakpoint-mcp:

npx breakpoint-mcp        # run on demand
# or
npm i -g breakpoint-mcp   # install the `breakpoint-mcp` command

To build from source instead:

cd host
npm install
npm run build   # tsc -> dist/

3. Register with your MCP client

Claude is the primary, tested client. Claude Code:

claude mcp add godot -- npx -y breakpoint-mcp

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "godot": {
      "command": "npx",
      "args": ["-y", "breakpoint-mcp"],
      "env": {
        "GODOT_BIN": "/abs/path/to/Godot",
        "GODOT_PROJECT": "/abs/path/to/your/project"
      }
    }
  }
}

Using a different MCP client (Cursor, VS Code, Windsurf, etc.)? See Compatibility below — the command is the same, only the config file and wrapper key differ.

Configuration (environment variables)

Var	Default	Meaning
GODOT_BIN	godot	Path to the Godot editor binary
GODOT_PROJECT	cwd	Project directory (contains project.godot)
BREAKPOINT_BRIDGE_HOST	127.0.0.1	Editor-bridge host
BREAKPOINT_BRIDGE_PORT	9080	Editor-bridge port (must match the addon)
BREAKPOINT_BRIDGE_TIMEOUT_MS	15000	Per-request timeout for editor tools
GODOT_LSP_HOST / GODOT_LSP_PORT	127.0.0.1 / 6005	GDScript language server
GODOT_DAP_HOST / GODOT_DAP_PORT	127.0.0.1 / 6006	Debug adapter
GODOT_LSP_TIMEOUT_MS / GODOT_DAP_TIMEOUT_MS	15000 / 20000	LSP / DAP timeouts
BREAKPOINT_RUNTIME_HOST / BREAKPOINT_RUNTIME_PORT	127.0.0.1 / 9081	In-game runtime bridge (must match the autoload)
BREAKPOINT_RUNTIME_TIMEOUT_MS	15000	Runtime request timeout
BREAKPOINT_TOOLSETS	(unset → all)	Comma/space list of tool groups or planes to enable — see Toolsets
BREAKPOINT_PRIVILEGED_GROUPS	(unset → none)	Comma/space list of the default-OFF capability groups to enable: code-execution, or all. Off → secure-default 280 tools; opting in loads the full 293 — see Safety & trust model

Renamed from CLAUDE_*: the BREAKPOINT_* variables above (plus BREAKPOINT_RESOURCE_COALESCE_MS) were named CLAUDE_* in earlier versions. The legacy CLAUDE_* names were honoured with a one-time deprecation warning in 1.0.0 and removed in 1.1.0 — use the BREAKPOINT_* names. GODOT_* variables are unchanged.

The full, annotated configuration reference is in the User Guide.

Toolsets (optional — load only the planes you need)

By default the server registers the full surface (293 tools). On Claude Code that costs nothing at decision time: Tool Search defers the catalog and loads each schema on demand (a measured ~86–98% upfront token reduction — the model never sees all 293 at once). For clients that can't defer tools, or when you just want a smaller default menu, set BREAKPOINT_TOOLSETS to a comma- or space-separated list of groups; only those register. The four planes already are the grouping, so the aliases mirror them:

Token	Enables
a	Plane A — live editor authoring (editor)
b	Plane B — headless CLI (cli)
c	Plane C — running-game runtime + verification family (runtime)
d	Plane D — GDScript & C# LSP/DAP (lsp,cslsp,dap,csdap)
csharp	The C# language-server + debugger groups (cslsp,csdap)
all	The full surface (the default)

…or any of the concrete group ids: cli editor lsp cslsp dap csdap runtime processes knowledge vcs assetgen netcode ba