一个引擎，一个 MCP，建立首次有效连接。

两种客户端的前置条件与路径

本教程面向 macOS / Linux 的 bash 或 zsh 终端中的本地 Codex CLI 与 Claude Code CLI。不适用于 ChatGPT / Claude 网页聊天、Claude Desktop、原生 Windows 或 WSL。Linux 仅核对文档语法，本地只检查了 macOS CLI 配置。

先按官方安装指南安装所选 CLI 并登录。安装 Node.js 18+ 及 npm/npx，并使用与现有项目兼容的 Godot 可执行文件。Coding-Solo 要求已安装 Godot，但未指定最低引擎版本；本步骤不保证所有 Godot 版本或 C# 工作流兼容。版本检查不需要编辑器插件。

两条路径均使用 @coding-solo/godot-mcp@0.1.1。客户端通过 npx 启动本地 stdio 子进程；此服务没有 HTTP 地址、端口、API 密钥或 MCP OAuth 登录。-y 会接受 npm 安装提示，执行前请检查链接的上游包。

复制前替换所有 /absolute/path/... 占位符。GODOT_PATH 指向可执行文件，不是项目目录或 app 目录。macOS 示例为 /Applications/Godot.app/Contents/MacOS/Godot；Linux 使用实际可执行文件，例如 /opt/godot/Godot。/absolute/path/to/My Game 是独立的项目目录，内部应包含 project.godot。含空格路径必须保留引号。

在即将启动客户端的同一终端执行以下检查。版本命令应输出版本；project.godot 检查应成功退出。保留 Godot --version 输出，用于对照首次工具响应。

node --version
npm --version
npx --version
"/absolute/path/to/godot" --version
test -f "/absolute/path/to/My Game/project.godot"

连接 Codex

添加服务

先检查 codex --version，再执行下方命令。godot-coding-solo 是本教程选定的配置名称，检查或移除时使用同名。覆盖已有条目前请先备份。

codex mcp add godot-coding-solo --env "GODOT_PATH=/absolute/path/to/godot" -- npx -y @coding-solo/godot-mcp@0.1.1

配置位置与作用域

CLI 添加命令写入用户级 ~/.codex/config.toml（自定义 CODEX_HOME 时位于该目录的 config.toml）。也可将下方 TOML 合并进该文件，不要覆盖其他设置或重复添加表。若仅用于项目，改放在已信任项目下的 .codex/config.toml 中，选择一种作用域即可。Codex 不使用 Claude Desktop 的 mcpServers JSON。

[mcp_servers.godot-coding-solo]
command = "npx"
args = ["-y", "@coding-solo/godot-mcp@0.1.1"]

[mcp_servers.godot-coding-solo.env]
GODOT_PATH = "/absolute/path/to/godot"

重启、连接与首次只读调用

运行 codex mcp get 检查保存的命令与环境变量，退出已有 Codex 会话，再从项目目录启动 codex。仅信任自己的工程，并检查工具授权请求。查看配置不会执行 Godot 工具调用。

codex mcp get godot-coding-solo
cd "/absolute/path/to/My Game"
codex

在交互式客户端中输入 /mcp，检查 godot-coding-solo。仅存在配置不等于连接成功：确认工具包含 get_godot_version 和 get_project_info，再发送下方只读提示。成功标志是实际发生 get_godot_version 工具调用，无报错且返回版本与终端一致。无需提前打开编辑器。

仅使用 godot-coding-solo MCP 服务调用 get_godot_version，参数为 {}。报告工具结果，不运行、编辑或创建任何项目文件。

之后如需检查项目，get_project_info 接受下方 JSON 作为工具参数。projectPath 不是服务启动参数，也不是 GODOT_PATH；应指向包含 project.godot 的目录，不是文件本身或 res:// 路径。对照实际项目检查返回的项目名称、路径、场景及脚本数量。首次只读测试仍使用引擎版本调用。

{
  "projectPath": "/absolute/path/to/My Game"
}

移除或恢复

codex mcp remove godot-coding-solo

此命令移除用户级条目。若使用项目 TOML，请仅删除其中 godot-coding-solo 表及 env 子表。恢复备份条目或重新执行添加命令后，启动新 Codex 会话。保留其他服务及项目文件。

连接 Claude Code

添加服务

先检查 claude --version，再进入项目目录添加服务。--scope local 使条目仅供你在该项目中使用。覆盖同名条目前先备份。客户端选项放在 -- 前，npx 及其参数放在后面。

cd "/absolute/path/to/My Game"
claude mcp add godot-coding-solo --transport stdio --scope local --env "GODOT_PATH=/absolute/path/to/godot" -- npx -y @coding-solo/godot-mcp@0.1.1

配置位置与作用域

local 作用域保存在 ~/.claude.json 的对应项目路径下，不是 .claude/settings.local.json。--scope user 会在 ~/.claude.json 中保存跨项目共享条目。团队使用可改为 --scope project：CLI 会在项目根目录生成下方格式的 .mcp.json。已有文件请合并，共享前检查机器专属路径，并在 Claude Code 提示时批准该项目服务。只选一种作用域，避免同名条目互相覆盖。

{
  "mcpServers": {
    "godot-coding-solo": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@coding-solo/godot-mcp@0.1.1"
      ],
      "env": {
        "GODOT_PATH": "/absolute/path/to/godot"
      }
    }
  }
}

重启、连接与首次只读调用

在同一项目目录执行 claude mcp get 检查条目，然后退出并用 claude 重启 Claude Code。上游 README 明确要求重启。出现提示时检查工作区信任和工具权限，不要关闭这些保护。

claude mcp get godot-coding-solo
claude

在交互式客户端中输入 /mcp，检查 godot-coding-solo。仅存在配置不等于连接成功：确认工具包含 get_godot_version 和 get_project_info，再发送下方只读提示。成功标志是实际发生 get_godot_version 工具调用，无报错且返回版本与终端一致。无需提前打开编辑器。

仅使用 godot-coding-solo MCP 服务调用 get_godot_version，参数为 {}。报告工具结果，不运行、编辑或创建任何项目文件。

之后如需检查项目，get_project_info 接受下方 JSON 作为工具参数。projectPath 不是服务启动参数，也不是 GODOT_PATH；应指向包含 project.godot 的目录，不是文件本身或 res:// 路径。对照实际项目检查返回的项目名称、路径、场景及脚本数量。首次只读测试仍使用引擎版本调用。

{
  "projectPath": "/absolute/path/to/My Game"
}

移除或恢复

cd "/absolute/path/to/My Game"
claude mcp remove --scope local godot-coding-solo

使用添加时的目录与作用域。若选了 project 或 user，将 local 替换为对应值。恢复备份条目或重新执行添加命令，然后重启 Claude Code。无需删除任何 Godot 项目文件。

排查这条 stdio 连接

• 连接失败或启动超时：检查包下载或网络错误，在设置 GODOT_PATH 后手动运行 npx -y @coding-solo/godot-mcp@0.1.1。stdio 服务可能静默等待输入，这本身不是连接测试。用 Ctrl+C 停止后交由客户端启动。Codex 若确因首次下载慢超时，可在服务表内、env 子表之前添加 startup_timeout_sec = 60。
• 找不到 Node/npx（ENOENT）：在启动终端执行 command -v node 和 command -v npx。修复 PATH，或将查到的 npx 绝对路径设为 command；该进程的 PATH 仍需能找到 Node。修改终端环境后重启客户端。
• 找不到 Godot 或版本不符：用保存的 GODOT_PATH 加引号并带 --version 执行。确认文件存在、可执行且是预期引擎。macOS 应选择 Godot.app 内部的二进制文件，而非 app 目录。重新检查客户端保存的环境变量。
• 路径含空格：按示例为整个 KEY=value 终端参数加引号。TOML/JSON 中路径保持为单个字符串，每个进程参数使用独立数组元素；不要把额外的 shell 引号字符写进路径值。
• 工具未出现：在 /mcp 查看启动错误，修改配置后重启，并检查实际作用域、工作目录、信任及启用状态。Codex 如自定义过 enabled_tools/disabled_tools，应检查过滤规则。Claude Code 应检查项目服务授权和 local/project/user 中的同名条目。组织策略可能限制 MCP，应联系管理员而非绕过。
• 项目路径错误：检查准确 projectPath 目录中的 project.godot 及客户端进程的文件访问权限。不要给 npx 追加虚构的 --project-path 参数。版本工具正常但项目检查失败时，应分别检查项目路径与引擎兼容性。

来源与验证边界

核对日期 2026-10-13：macOS arm64 上的 Codex CLI 0.162.1、Claude Code 2.1.231、Node 25.1.0；npm 包 0.1.1 及上游提交 1209744fad78f3998f98c7394fd0f6ef50da5281 的 README/源码。已核对官方文档、CLI 帮助及隔离环境中的添加/查看/移除配置。未实测 Codex/Claude Code → MCP → Godot 端到端会话；上述成功标志是操作指引，不是实测结果。

• OpenAI 官方 MCP 文档
• Claude Code 官方 MCP 文档
• 固定版本 Coding-Solo README 与源码
• 已发布 npm 包 0.1.1

原有未固定版本的 Claude Code 快速命令与上游一致，继续保留。本教程补充 -y、固定包版本、明确 stdio/作用域及 GODOT_PATH。其他 MCP 不可直接替换：Godot AI 使用编辑器生成的 attach 配置，Runtime 使用自己的包和桥接，Full Control 需要源码构建与运行时 autoload。请遵守各自要求并使用下方原有章节；这里不提供全客户端兼容矩阵。