Godot MCP Gateway

English | 简体中文

One Godot editor, multiple AI coding agents.

Godot MCP Gateway is a local control plane that lets Codex, Claude Code,OpenCode, Pi, and other MCP clients share a single Godot editor safely. Eachclient keeps an independent MCP session while one machine-wide Gateway ownseditor discovery, request routing, write scheduling, playtest access, the GodotLSP connection, and reconnects.

Project status: early development. The v1 Gateway topology, heterogeneousbatch execution, and editor activity UI are implemented, but the project hasnot yet published a stable release.

Why a Gateway?

Most Godot MCP integrations start one server and claim one editor port for everyAI client. That model becomes fragile when several agents work on the sameproject. This project separates agent sessions from the editor connection:

Codex -------- stdio shim --\
Claude Code -- stdio shim ---+-- local IPC -- Gateway -- WebSocket -- Godot Editor
OpenCode ----- stdio shim ---/                   |-- Playtest Runtime
Pi ----------- stdio shim --/                    `-- Godot LSP

The Godot plugin connects outward to the Gateway. Agents never claim Godot portpools or connect directly to the editor.

Highlights

Multi-agent sessions: every MCP client has its own identity, lifecycle,and activity stream.
One editor connection: the Gateway owns editor, runtime, and LSP routing.
Ordered writes: editor mutations from different agents are scheduled FIFO.
Cross-tool batches: batch runs heterogeneous MCP tools sequentially,stops on failure, and prevents other agents' writes from interleaving.
Visible operations: the Godot Dock shows connected agents, queued andrunning work, batch progress, and recent results.
Editor focus: successful mutations can select and focus the affected node.
Full toolkit base: the upstream Godot tool catalogue remains availablethrough the Gateway architecture.

Requirements

Godot 4.2 or newer
Node.js 22 or newer
npm

Run from source

Clone and build the repository:

git clone https://github.com/di404/godot-mcp-gateway.git
cd godot-mcp-gateway
npm install
npm run build

Copy addons/godot_mcp_gateway/ into your Godot project's addons/ directory,then enable Godot MCP Gateway under Project Settings → Plugins.

Start the machine-wide Gateway in a terminal and leave it running:

npm run start:gateway

Configure each MCP client to launch its own stdio shim. Replace/absolute/path/to/godot-mcp-gateway with the clone's absolute path:

{
  "mcpServers": {
    "godot-mcp-gateway": {
      "command": "node",
      "args": [
        "/absolute/path/to/godot-mcp-gateway/packages/server/dist/index.js",
        "stdio"
      ],
      "env": {
        "GODOT_MCP_PROJECT_PATH": "/absolute/path/to/your-godot-project"
      }
    }
  }
}

If the MCP client starts in the Godot project root,GODOT_MCP_PROJECT_PATH can be omitted. Set GODOT_MCP_AGENT_NAME to overridethe agent label shown in the Dock.

Batch example

The batch tool accepts ordinary registered tool calls:

{
  "calls": [
    {
      "tool": "scene_get_tree",
      "arguments": { "max_depth": 1 }
    },
    {
      "tool": "project_get_settings",
      "arguments": { "prefix": "application/" }
    }
  ]
}

Calls run in order through the normal validation and tool pipeline. Executionstops at the first failed or cancelled step, and remaining steps are markedskipped. Nested batches and output references are not supported in v1.

Repository layout

addons/godot_mcp_gateway/ — Godot editor plugin, tool handlers, and Dock.
packages/server/ — Gateway process, stdio MCP surface, IPC, tool catalogue,scheduling, runtime routing, and LSP ownership.
docs/ — architecture, protocol, contributor, compatibility, and localtesting documentation.

The repository root is also a small Godot project for developing and exercisingthe plugin. Start with the documentation index for deeperguides.

Current v1 boundaries

One Gateway accepts one Godot editor and one active playtest runtime.
The Gateway is started manually and runs in the foreground.
A batch is failure-stop, with each mutation retaining its own Undo step.
Nested batches and step-output references are intentionally deferred.

Attribution and license

This project is an active fork of NPGameDev'sGodot MCP Toolkit andGodot MCP Server. Their maturetool catalogue and editor integration form the feature base; this fork changesthe connection topology around them.

Source code is available under the MIT License. SeeATTRIBUTIONS.md for preserved upstream notices and third-partyacknowledgements. Inherited upstream artwork is development material and is notlicensed as this fork's independent brand asset; replace it before distributinga branded release.

Godot MCP Gateway