首页/文章/开发工具

在 Codex 中接入 Cocos Creator MCP：安装、场景操作与验证边界

太阳作者太阳
原创内容采用 CC-4.0 协议发布，转载请注明出处
Cocos CreatorCocos CLIMCPCodex游戏开发

我想让 Codex 直接操作 Cocos Creator 的场景、节点和组件，于是安装了 Cocos CLI 提供的 MCP 服务。

我使用的是 Cocos Creator 3.8.8，安装时 Cocos CLI 为 0.0.1-alpha.35。看起来只有几条安装命令，实际先后碰到了 npm 配置、sharp、gl、项目依赖和 Windows 端口问题。这篇文章记录最后跑通的过程。

安装 Cocos CLI

仓库的 .nvmrc 指定 Node.js 22.17.0。Windows 还要准备 Git、Cocos Creator 和带 C++ 工具链的 Visual Studio Build Tools。

git clone https://github.com/cocos/cocos-cli.git C:\app\install\cocos\cocos-cli
Set-Location C:\app\install\cocos\cocos-cli

npm config fix --location=project
npm install --global node-gyp
npm run init
npm install

npm install-scripts ls
npm install-scripts approve --all
npm rebuild --foreground-scripts

npm run download-tools
npm run build
npm link

npm 12 会拦截没有列入 allowScripts 的依赖安装脚本。先用 npm install-scripts ls 查看列表，确认后再批准。批准操作不会补跑已经跳过的脚本，所以还要执行一次 npm rebuild --foreground-scripts。

approve --all 会修改这个克隆仓库的 package.json。我只在核对列表后对 Cocos CLI 使用它，没有把它设成全局习惯。

安装后检查命令和两个原生模块：

cocos --version
cocos -h
cocos start-mcp-server -h
Get-Command cocos

node -e "require('sharp'); console.log('sharp OK')"
node -e "require('gl'); console.log('gl OK')"

本机帮助比 README 更可靠。我安装的版本只有 build、create、make、preview、run、start-mcp-server 和 upload 等命令。

安装时遇到的错误

ERR_INVALID_AUTH

第一次执行 npm run init 时，npm 12 报错：

Invalid auth configuration found:
`email` must be renamed to `//registry.npmmirror.com/:email`

问题来自项目 .npmrc 里的旧写法，不是账号密码。进入 Cocos CLI 目录修复项目配置：

npm config fix --location=project

sharp 和 gl 没有安装完整

启动 MCP 时又出现：

Cannot find module '../build/Release/sharp-win32-x64.node'
Cannot find module '../build/Release/webgl.node'

两个包都在 node_modules 中，但它们的安装脚本被 npm 12 拦截了。npm rebuild 即使显示成功，只要前面还有下面这条警告，模块仍然不可用：

install scripts blocked because they are not covered by allowScripts

处理方法就是回到安装目录，批准脚本后重建：

Set-Location C:\app\install\cocos\cocos-cli

npm install-scripts ls
npm install-scripts approve --all
npm rebuild --foreground-scripts

node -e "require('sharp'); console.log('sharp OK')"
node -e "require('gl'); console.log('gl OK')"

我没有单独安装其他版本的 sharp 或 gl，而是继续使用仓库锁定的依赖。

启动 MCP

进入 Cocos 项目目录：

Set-Location C:\source\REPO\apps\client
cocos start-mcp-server --project . --port 9527

从仓库根目录启动也可以：

cocos start-mcp-server --project .\apps\client --port 9527

项目依赖也要先构建

MCP 启动时会加载目标项目。我这里的 Cocos 脚本导入了：

import { /* ... */ } from "sparrow/games";
import { /* ... */ } from "sparrow/simulate";

这两个入口指向工作区包的 dist，当时文件还没有生成。先构建依赖：

Set-Location C:\source\REPO
npm run build -w apps/sparrow

Test-Path .\apps\sparrow\dist\games.js
Test-Path .\apps\sparrow\dist\simulate.js

两条检查都返回 True 后再启动 MCP。日志里如果同时出现模块找不到和一串依赖断言，先处理最早的 module not found。

9527 启动了，9230 仍可能失败

--port 9527 指定的是 MCP HTTP 端口。场景进程还会从 9230 开始找内部端口，所以我看到过两条看似矛盾的日志：

MCP Server started successfully
创建场景进程失败: listen EACCES: permission denied 0.0.0.0:9230

HTTP 服务虽然启动了，场景工具仍然不能用。先查 Windows 排除端口：

netsh interface ipv4 show excludedportrange protocol=tcp
netsh interface ipv6 show excludedportrange protocol=tcp

我这台机器的 9230 落在排除范围内，同时还有旧的 MaxUserPort=15000。系统配置的处理过程见排查 Windows 动态端口与保留端口冲突。

当前版本的 Cocos CLI 只会在 EADDRINUSE 时换端口，没有跳过 EACCES。临时修改 src/server/utils/index.ts：

if (err.code === "EADDRINUSE" || err.code === "EACCES") {
  resolve(getAvailablePort(port + 1));
  return;
}

修改后重新构建：

Set-Location C:\app\install\cocos\cocos-cli
npm run build

还要确认 dist/server/utils/index.js 中已经出现 EACCES。只改源码、不保存或不构建，cocos 命令仍会执行旧代码。

让 Codex 连接 MCP

在项目的 .codex/config.toml 中加入：

[mcp_servers.cocos_cli]
url = "http://127.0.0.1:9527/mcp"
enabled = true
required = false
default_tools_approval_mode = "approve"
startup_timeout_sec = 30
tool_timeout_sec = 120

我没有把它设为必需服务。平时不启动 Cocos MCP，也不会影响其他 Codex 工作。

配置完成后，让 Codex 查询一次当前场景和项目资源。能读到 Creator 中的真实内容，才说明场景进程也正常。只检查 9527 端口不够。

场景操作不能只写脚本

最初 Codex 创建了一个组件脚本，随后开始构建和预览。我打开 Creator 后却发现，场景里没有新节点，组件也没有挂载。

Cocos 场景是序列化资产。写完脚本以后，还要通过 MCP 完成这些操作：

  1. 打开目标场景并查询节点。
  2. 把入口组件挂到真实节点上，设置属性。
  3. 保存场景，再次查询节点和组件。

界面可以在运行时创建，但场景里最好保留一个能看见的入口。否则很难确认代码是否会执行。

快速检查不需要完整构建

当前 Cocos CLI 没有独立的 check 命令。我在项目里使用 TypeScript 检查：

{
  "scripts": {
    "check": "npm run typecheck",
    "typecheck": "tsc -p tsconfig.json --noEmit"
  }
}
npm run check

接着通过 MCP 刷新改过的资源，再读取 Creator 最新的 error 和 warn 日志。tsc --noEmit 不会发现所有资源导入问题，Creator 日志也可能保留旧错误，需要留意时间。

预览和最终验证留在 Creator

我实际调用过一次 builder_run。工具返回成功，并给出：

http://localhost:9527/build/web-desktop/web-desktop/index.html

这个地址是 404，实际能打开的是：

http://localhost:9527/

这次以后，我不再让 Codex 调用 builder_*，也不让它执行 CLI 的 build、make、preview、run 和 upload。

现在的流程很简单：Codex 修改场景和资源，保存后重新查询，再跑 TypeScript 检查并读取 Creator 日志。构建、预览和画面确认由我在 Cocos Creator 中完成。

参考资料