Godot MCP Gateway

English | 简体中文

一个 Godot 编辑器，多个 AI 编码代理。

Godot MCP Gateway 是一个本地控制平面，让 Codex、Claude、OpenCode、Pi 等 MCP 客户端能够安全地共享同一个 Godot 编辑器。每个客户端保持独立的 MCP 会话，而一个机器级的 Gateway 统一负责编辑器发现、请求路由、写入调度、试玩访问、Godot LSP 连接以及重连。

项目状态： 早期开发阶段。v1 Gateway 拓扑、异构批量执行和编辑器活动界面已实现，但项目尚未发布稳定版本。

为什么需要 Gateway？

大多数 Godot MCP 集成会为每个 AI 客户端启动一个服务器并占用一个编辑器端口。当多个代理在同一个项目上工作时，这种模式会变得脆弱。本项目将代理会话与编辑器连接分离：

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

Godot 插件主动向外连接 Gateway。代理不会占用 Godot 端口池，也不直接连接编辑器。

Related MCP server: agent-bus-mcp

亮点

• 多代理会话： 每个 MCP 客户端都有自己的身份、生命周期和活动流。

• 单一编辑器连接： Gateway 统一管理编辑器、运行时和 LSP 路由。

• 有序写入： 来自不同代理的编辑器变更按 FIFO 顺序执行。

• 批量操作： batch 按顺序运行异构 MCP 工具，失败即停止，并防止其他代理的写入交错执行。

• 操作可视化： Godot 停靠面板显示已连接的代理、排队中和正在运行的任务、批处理进度以及最近的结果。

• 编辑器聚焦： 成功的变更可以自动选中并聚焦受影响的节点。

• 完整工具包基础： 上游 Godot 工具目录仍然可以通过 Gateway 架构使用。

环境要求

• Godot 4.2 或更高版本

• Node.js 22 或更高版本

• npm

从源码运行

克隆并构建仓库：

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

将 addons/godot_mcp_gateway/ 复制到你的 Godot 项目的 addons/ 目录中，然后在 Project Settings → Plugins 下启用 Godot MCP Gateway。

在终端中启动机器级的 Gateway，并保持其运行：

npm run start:gateway

配置每个 MCP 客户端以启动自己的 stdio shim。将 /absolute/path/to/godot-mcp-gateway 替换为克隆仓库的绝对路径：

{
  "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"
      }
    }
  }
}

如果 MCP 客户端在 Godot 项目根目录中启动，则可以省略 GODOT_MCP_PROJECT_PATH。设置 GODOT_MCP_AGENT_NAME 以覆盖在 Dock 中显示的代理标签。

批量示例

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

batch 工具按顺序执行异构 MCP 工具的注册，遇到失败或取消则停止，并阻止其他代理的写入交错插入。嵌套批处理和输出引用不被支持。

当前 v1 边界

• 一个 Gateway 对应一个编辑器和一次激活的试玩运行时。

• Gateway 在前台运行。

• 每个变更操作保留自己的撤销步骤。

• 嵌套批处理和步骤输出引用暂不支持。

归属与许可

本项目是 NPGameDev 的 Godot MCP Toolkit 和 Godot MCP Server 的一个活跃分支。上游 Godot 工具目录构成了功能基础；此分支改变了它们周围的连接拓扑。

源代码根据 MIT 许可证 提供。请参阅 ATTRIBUTIONS.md 以获取保留的上游声明和第三方致谢。继承的上游美术资源是开发素材，并非本分支的独立品牌资产；请勿将其用于品牌发布。