godot-mcp-native · v2.0.0 · MIT · Windows · macOS · Linux

A native MCP server that reaches into a running Godot editor.

Didi is a C++20 Model Context Protocol server for Godot 4.5+. A standalone binary speaks MCP to your assistant, a GDExtension speaks Godot inside the editor, and between them is a local named pipe rather than a network. Live scene objects, native undo history, real pixels, and an honest implemented: false wherever it cannot execute.

Five-minute quickstart GitHub Download v2.0.0

116canonical tools
113implemented today
1137tests in the suites
0runtime dependencies
4.5+Godot, editor and game

How it works

The mark is the architecture.

A node enters a ring through a pipe. That is the whole request path: an MCP client, a local named pipe or Unix socket, and the live Godot scene it reaches into. Left to right is the direction of every call.

Node · the client

Your assistant

Claude Code, Claude Desktop, Cursor, VS Code, Windsurf or Antigravity launches didi and speaks MCP over stdio. Every definition carries specification annotations and _meta.didi execution metadata, so a client can see whether a tool is live, offline, unavailable or unimplemented before it calls.

Pipe · the bridge

Didi

One C++20 binary, didi or didi.exe: the JSON-RPC dispatcher, the registry of 116 canonical tools, godot:// resources and prompt workflows, and an offline engine that parses GDScript and .tscn files when no editor is running. It reaches the editor over an authenticated, process-unique local IPC endpoint.

Ring · the scene

Godot 4.5+

The Didi GDExtension inside the editor dispatches on the main thread through EditorInterface, edits the live SceneTree through EditorUndoRedoManager, and captures the real viewport as PNG. A running game publishes a session the same way, with its own smaller set of live tools.

Why Didi

Native, local, and explicit about what it can actually execute.

Most bridges into Godot either drive the command line, which cannot see the editor, or chain a Node.js process, a WebSocket and a plugin, which can. Didi is the plugin and the server in one native binary each, with nothing between them but a pipe.

Feature	Script and CLI wrappers	Multi-hop network bridges	Didi
Execution topology	Offline CLI subprocesses	Node.js, WebSocket and a C# plugin	Direct C++ GDExtension plus a standalone binary
In-memory scene access	Blind to live editor state	Depends on the bridge	Direct Godot objects for every live tool
Undo and redo safety	None; files are overwritten	Varies	Native `EditorUndoRedoManager` transactions
Visual inspection	None	Often needs an export	Live editor PNG capture, node isolation, exact pixel diffs
Transport	A process start per call	Network or a multi-process bridge	Local named pipe or Unix socket
External dependencies	Node.js or Python runtime	Node.js runtime plus WebSockets	None at runtime

Platforms

Windows, macOS and Linux.

Every release ships a built archive for all three, with checksums and build provenance, and every push builds Didi and runs the suites on all three. The live editor harness runs on Windows in CI, so that is where Didi has the most hours behind it, and the other two are where a tester is worth the most.

Windows x64

didi-windows-x64.zip · didi.exe

MSVC build, the native and Python suites, and the live Godot editor harness on 4.5.1, 4.6.2 and 4.7.2, on every push. The platform Didi is developed on.

Linux x64

didi-linux-x64.tar.gz · didi

gcc build, the suites, and an ASan and UBSan run on every push. The archive is built in an Ubuntu 22.04 container so it runs on older glibc. No live editor run in CI yet.

macOS Apple silicon

didi-macos-arm64.tar.gz · didi

clang build and the suites on every push. No Intel archive, and no live editor run in CI yet.

Testers wanted on macOS and Linux

Those are the least-tested platforms. If you run Didi there, tell us how it went, good or bad: the Godot version, the client, and what the Didi tab's Diagnostics page reported. Every run is evidence CI does not have.

Report a run

The surface

116 canonical tools across fourteen domains.

The canonical names are the stable protocol surface; 10 legacy names are registered beside them for older clients, 126 entries in tools/list. Availability is stated per definition rather than implied by a name.

Scene tree and nodes 7

scene_get_hierarchy · scene_instantiate_node · scene_remove_node · scene_reparent_node · scene_set_property · scene_get_property · scene_duplicate_node

Live against the edited scene. The hierarchy also has an offline .tscn fallback.

Signals and events 4

signal_list_connections · signal_connect · signal_disconnect · signal_emit

Connect and disconnect land in the scene's undo history. Emit requires confirmation.

Scripting and reflection 4

script_check_syntax · script_reflect_class · script_get_symbols · script_patch_method

Offline and file-based. Reflection covers every engine class from the pinned Godot API dump.

Vision and render 5

viewport_capture_frame · viewport_diff_capture · viewport_set_camera_transform · viewport_create_test_lab · viewport_toggle_debug_draw

Real editor pixels with a process-local capture ID, reversible node isolation, and exact RGBA diffs.

Physics and navigation 6

physics_raycast_query · physics_simulate_step · nav_bake_mesh · nav_query_path · anim_list_tracks · anim_play_track

Raycasts and path queries run against the existing worlds in the editor or a game. Stepping and baking are API-blocked and say so.

Tilemaps and GridMaps 3

tilemap_set_cells · tilemap_get_used_rect · gridmap_set_cells

Editor-only batch editing: the whole request is preflighted, then applied as one undo action.

Resources and files 9

resource_create · resource_inspect · project_list_resources · project_get_uid_map · project_audit_assets · project_analyze_impact · project_search_text · project_search_symbols · asset_reimport

Bounded offline search, impact analysis and import health. Reimport is editor-only and waits for a stable idle editor.

Runtime and debug 4

runtime_launch · runtime_inject_input · runtime_get_call_stack · runtime_read_profiler

Bounded child launches, explicit press and release events into a game, live Performance monitors. The call stack is API-blocked.

Editor lifecycle 4

editor_undo · editor_redo · editor_save_scene · editor_reload_project

Live. Reload asks the editor for a resource-filesystem rescan rather than restarting anything.

Project wiring 18

script attach and detach · autoloads · InputMap · settings · groups · scene create, open, close and pack

Live with undo history, atomic ProjectSettings writes, overwrite guards and normalized res:// paths.

Runtime sessions 10

runtime_list_sessions · attach, detach, get · logs and output · pause, step, stop, tree · eval_gdscript

Attachment is deterministic or explicit and always authenticated. Evaluation is a strict read-only expression subset, not arbitrary GDScript.

Deep domains 6

csharp_check_build · shader_check_compile · project_list_export_presets · project_export · gridmap_export_mesh_library · ui_hit_test

Bounded subprocesses with no shell, per-request deadlines, a 1 MiB output cap and project-contained output paths.

Agent coordination 10

blackboard_write · blackboard_read · blackboard_patch · blackboard_list_keys · blackboard_clear · blackboard_task_create, claim, update, complete, list

File-backed under .didi/blackboard/ with an exclusive OS lock per operation and expiring leases, so two agents racing for one task produce a single winner.

Managed recovery 4

runtime_recovery_status · runtime_checkpoint · runtime_recover_editor · runtime_restore_checkpoint

Opt-in owned editor, a separate project copy, saved-file checkpoints, one automatic restart, confirmed restore.

Resources and prompts

godot://project/tree · godot://editor/state · runtime logs · prompt workflows

Dynamic resources for the project tree and editor state, plus prompt templates an agent can follow. Resources and prompts.

Honest by construction

113 of the 116 canonical names are implemented in at least one mode. The remaining 3 are registered so the surface is stable, carry implemented: false, and return a tool error when called. Nothing pretends. The three are blocked by the engine API, and the evidence for that is public.

physics_simulate_step
nav_bake_mesh
runtime_get_call_stack

Read the metadata, not the name

Every definition in tools/list says how it runs right now: executionModes, implemented, currentMode, liveAvailable, editorConnected and the selected sessionKind. A tool with no editor behind it reports unavailable, and a tool with an offline path reports offline_fallback only when a live call would have been better.

Current capability matrix · Tool reference · Feasibility evidence

Safety

An agent with real access needs real brakes.

Didi edits the project that is open in front of you. So every mutation can be previewed, the dangerous ones need a token the preview issued, and the person at the editor can undo what the agent did.

An explicit project, always

Didi refuses to start without --project or DIDI_PROJECT_ROOT, and the directory must contain project.godot. Endpoint names carry a stable project key.

One client per session

A per-session OS lock admits one MCP client at a time and is released when that client exits. The blackboard tools are how separate agents share decisions instead.

Dry-run on every mutation

Every implemented mutation advertises dry_run and answers with a handler-free change plan bound to the exact project and live route.

Confirmation tokens

Always-confirmed and overwrite-confirmed tools need the 64-hex, 120-second, single-use confirmation_token that the exact preview returned.

Native undo

Scene mutations register with the edited scene's EditorUndoRedoManager history. Ctrl+Z in the editor works on what the agent did.

Annotations that mean it

readOnlyHint, destructiveHint, idempotentHint and openWorldHint on every definition, with the managed-mode restart caveat stated rather than hidden.

Bounded live work

A 15-second main-thread deadline. Work that never started says not_started; work that started and did not resolve says unknown_outcome and quarantines the route, so nothing blindly retries a mutation.

Authenticated local IPC

A process-unique endpoint, owner-only session descriptors, and a session ID bound to PID plus process start time. Public responses never include the token.

Crash recovery, opt in

Start with --managed-editor and --recovery-workspace and Didi edits a separate project copy, checkpoints saved files, and can restart its owned editor once without replaying an uncertain edit.

Setup

Sixty seconds, three steps.

Build the binary and the addon together, enable the plugin, point your assistant at the binary. The in-editor console generates the third step for you with the binary already located. The full quickstart covers each client by hand, and the release page has built archives for Windows, Linux and macOS with checksums and build provenance.

Step 1 · build

# Release binary and the complete addon, assembled under build/
git clone https://github.com/saworbit/didi.git
cd didi
cmake -B build -S .
cmake --build build --config Release

On Windows this produces build/Release/didi.exe and build/addons/didi/ with the extension library inside it.

Step 2 · enable

your_game/
├── addons/
│   └── didi/          ← copy build/addons/didi here
│       ├── plugin.cfg
│       ├── didi.gdextension
│       └── bin/
└── project.godot

Open the project, then Project → Project Settings → Plugins and enable Didi Native MCP Bridge. A Didi tab appears beside 2D, 3D and Script.

Step 3 · connect

{
  "mcpServers": {
    "didi": {
      "command": "D:/didi/build/Release/didi.exe",
      "args": ["--project", "D:/my_game"]
    }
  }
}

Into claude_desktop_config.json, .cursor/mcp.json or your client's equivalent. Or open the Didi tab's Connect page and copy the generated one.

In the editor

Can my assistant reach this project right now?

Enabling the plugin adds a Didi main screen to the editor. It answers the question every bridge raises first, without anyone reading a log: six cards, each with a red, amber or green light, the fact behind it, and the one thing to do about it.

DashboardConnectLogSettingsDiagnostics

Live bridge Auto refresh Technical detail

Live bridgeUp for 14 min

ExtensionLoaded · addons/didi/bin

Server binaryVerified by running it

Client configurationAbsent Write it

This editorSession 3f9c… · pid 18240

Other sessionsNone competing

Switches that do something

Live bridge opens and closes the bridge for real, loading and unloading the extension and reporting the status Godot returns, including the one that means "not without a restart". Auto refresh re-reads state on a timer. Technical detail reveals the session id, the endpoint, the descriptor path and the other sessions on the machine.

The other four tabs

Connect generates the launch configuration for Claude Code, Cursor, Claude Desktop and VS Code, and can write it into the project. Log shows the console's own record and Godot's log for the last run, filterable by level and text. Settings lives in your editor's EditorSettings, where nothing in the project can change it. Diagnostics names the path or pid behind every check and copies into an issue. The console never displays, copies or reports a session token.

Documentation

Every page, grouped by what you came for.

The documentation lives in the repository so it is versioned with the code it describes. The index lists every page, including the design records and their status.

Start here

QuickstartGodot and one assistant in about five minutes.
Integration guideInstalling the addon into an existing project and wiring each client.
Instructions for agentsThe system prompt and decision tree to hand an assistant.
Managed recoveryOwned editor, checkpoints, reconciliation, and recovery limits.

What Didi does today

Capability matrixThe authoritative list of live, offline, unavailable and unimplemented.
Tool referenceBehaviour, arguments and limits for every canonical tool and legacy name.
Resources and promptsThe godot:// resources and the prompt templates.
Control roomThe MCP Apps dashboard rendered inside your assistant.

How it works

ArchitectureThe C++20 design, the dual topology, threading, and the IPC transport.
API and wire protocolJSON-RPC 2.0 over the wire and the binary frame format.
AdministrationDACL hardening, headless CI, observability, troubleshooting.
Developer guideBuilding from source, the test suites, and adding a tool.
Test inventoryGenerated. What each suite contains and how many cases it runs.

Where it is going

RoadmapCompleted phases and the technical build order.
Surface amendmentsEvery accepted change to the canonical tool surface.
Phase 7 feasibility gateReproducible results on Godot 4.5.1 and 4.7.2, and the three blocked contracts.
Future phasesThe design for what follows Phase 6.

The project

ChangelogVersion history, and what a version number does and does not promise.
Security policySupported release line, the local attachment boundary, private reporting.
ContributingBuild, test and review expectations for a change you want merged.
On the use of AIWhere AI was used, what checks it, and who is responsible when it is wrong.
Third-party codeThe vendored sources no package manager resolves.