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. Each client keeps an independent MCP session while one machine-wide Gateway owns editor discovery, request routing, write scheduling, playtest access, the Godot LSP connection, and reconnects.

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

Why a Gateway?

Most Godot MCP integrations start one server and claim one editor port for every AI client. That model becomes fragile when several agents work on the same project. 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 port pools 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 and running 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 available through 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 override the 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. Execution stops at the first failed or cancelled step, and remaining steps are marked skipped. 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 local testing documentation.

The repository root is also a small Godot project for developing and exercising the plugin. Start with the documentation index for deeper guides.

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's Godot MCP Toolkit and Godot MCP Server. Their mature tool catalogue and editor integration form the feature base; this fork changes the connection topology around them.

Source code is available under the MIT License. See ATTRIBUTIONS.md for preserved upstream notices and third-party acknowledgements. Inherited upstream artwork is development material and is not licensed as this fork's independent brand asset; replace it before distributing a branded release.