Godot Universal

Local-first MCP tooling for Godot: a TypeScript/Node.js stdio server plus a GDScript editor addon and an optional development-runtime bridge.

The addon does not require C# or a .NET Godot build. A game that uses C# still needs Godot .NET and the corresponding SDK to compile its own code. Native node, scene and exported-property inspection uses Godot's APIs rather than assuming a particular game scripting language.

Architecture

MCP client -- stdio / MCP --> Node.js server
                              | authenticated, loopback-only NDJSON TCP
                              +--> GDScript editor bridge (default 9500)
                              +--> GDScript runtime bridge (default 9501, opt-in)

Keep the public MCP protocol in the official Node SDK. The internal TCP bridge is not itself a public MCP endpoint. See the bridge guide for the language boundary, security model, migration notes and limitations.

Run this checkout

Use Node.js 20 or newer and a Godot 4 editor. The integration matrix includes Godot 4.3 standard and 4.4.1 .NET; it is a compatibility test matrix, not a claim that these are the newest or recommended engine releases. Check the actual CI results for the revision being installed.

git clone https://github.com/Noa3/GodotMCP.git
cd GodotMCP
npm ci
npm run build

When evaluating a pull request, check out its branch before building. Copy the complete addons/godot_universal_mcp directory into your game's addons/ directory. Enable Godot Universal MCP under Project > Project Settings > Plugins, then open a scene. Do not mix files from different addon revisions.

Configure your client to launch the built file with absolute paths. Example VS Code .vscode/mcp.json (replace both paths):

{
  "servers": {
    "godot-universal": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/GodotMCP/dist/cli/index.js"],
      "env": {
        "GODOT_PROJECT_ROOT": "/absolute/path/to/your-game"
      }
    }
  }
}

On Windows, forward-slash absolute paths such as C:/Projects/... avoid JSON backslash escaping. Other MCP clients may use a different outer configuration key; the command, arguments and environment are the same. No serve subcommand is needed. Using npx to launch a registry release does not test this checkout. This guide makes no assumption that a matching npm release has been published.

The dock's Copy Config button generates this VS Code configuration after godot_universal_mcp/server_entry is set in Project Settings to the absolute built dist/cli/index.js path. The project token is not put on the clipboard.

Authentication and write access

On first activation, the editor creates a random project-local credential at .godot/godot_universal_mcp/token. The Node server reads that game's token before each request. GODOT_PROJECT_ROOT must point to the game, not this server's repo. The .godot cache must stay private and out of version control. An optional GODOT_MCP_TOKEN override must be the same in the editor and server environments.

The MCP server defaults to read-only. To allow changes in a project you trust, first initialize its config:

node dist/cli/index.js init-project /absolute/path/to/your-game

Then manually edit only these fields in the generated .godot-universal-mcp/config.json, retaining the other settings:

{"security": {"allowWrite": true, "trustMode": "trusted"}}

All registered write/destructive tools, including editor saves and process launch/control, require both fields. Tool annotations are hints for clients, not an alternative to this authorization. Possession of the raw bridge token grants bridge access; this is not a sandbox against other processes running as you. Only open and run projects you trust.

Runtime inspection

Enable Runtime bridge (next game run) in the dock and launch the game using the editor or an editor binary. The addon manages its own autoload entry. The runtime listener is disabled by default and refuses normal export-template builds, including debug exports. It remains responsive while gameplay is paused. Changing the runtime checkbox takes effect on the next game run.

Main bridge-backed MCP tools

Public tool	What it actually does
godot_editor_status, godot_editor_capabilities	Read engine/project identity and supported operations.
godot_editor_tree, godot_editor_get_node	Inspect the current, possibly unsaved edited scene.
godot_editor_set_node_property	Typed property edit through editor Undo/Redo; trusted writes required.
godot_editor_save_all, godot_editor_filesystem_scan	Request scene saves or a filesystem scan.
godot_runtime_status, godot_runtime_tree, godot_runtime_perf	Inspect the running game through the opt-in bridge.
godot_runtime_pause, godot_runtime_resume	Pause/resume without pausing the bridge itself.
godot_runtime_screenshot	PNG JSON payload, longest edge capped at 1024; unavailable headlessly.
godot_runtime_logs	Bounded stdout/stderr from a process launched by this server.

Editor nodes use paths relative to the edited root (. means the root). Runtime nodes use paths relative to /root. Missing/unimplemented functionality returns explicit errors: godot_editor_output does not yet capture the editor console. Empty log arrays must not be treated as proof of an error-free game. The existing project/file/offline scene/script tools remain available; their textual analysis is not a complete Godot or C# compiler.

Development checks

npm run typecheck
npm run lint
npm test
npm run build
node --test tests/client.test.cjs
python3 tests/bridge_smoke.py --godot /absolute/path/to/godot

For the compiled C# fixture, use a Godot .NET binary and the matching .NET SDK:

python3 tests/bridge_smoke.py --godot /path/to/godot-dotnet --csharp --sdk-version 4.4.1

The smoke test creates a temporary project and exercises real editor/runtime TCP connections, authentication, exported properties, typed writes, batching and pause/resume. It does not replace GUI undo testing, rendered screenshot testing, or exported-build validation. CI runs the engine fixtures separately from the TypeScript/Jest checks.

Documentation and license

Bridge guide and migration · Security · Roadmap · Contributing

MIT License. See LICENSE, NOTICE.md, and THIRD_PARTY_NOTICES.md.