首页/文章/开发工具
在 Codex 中接入 Cocos Creator MCP：安装、场景操作与验证边界
太阳作者太阳
原创内容采用 CC-4.0 协议发布，转载请注明出处
Cocos CreatorCocos CLIMCPCodex游戏开发

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

我手里有一个刚创建的 Cocos Creator 项目，场景基本还是空的。我希望 Codex 不只是帮我写脚本，还能直接操作 Creator 里的场景、节点和组件。正好 Cocos CLI 已经提供了 MCP 服务，于是我准备把它接进 Codex。

安装和连接都不算麻烦，真正折腾人的是后面的使用方式。Codex 能调用这些工具，不等于它知道应该先做什么。它一度反复构建、启动预览，甚至另外开了一个 Python 静态服务器，而我打开 Creator 一看，场景里根本什么都没挂。

这篇文章记下我最后保留的配置，也说说我是怎么把这套流程纠正过来的。

先把 Cocos CLI 装好

我使用的是 Cocos Creator 3.8.8，安装时 Cocos CLI 的版本为 0.0.1-alpha.35。按照项目仓库里的说明，电脑上要先有 Node.js 22.17、Git 和 Cocos Creator。Windows 还需要 Visual Studio C++ 构建工具。

CLI 目前要从源码安装：

git clone https://github.com/cocos/cocos-cli.git C:\app\install\cocos\cocos-cli
Set-Location C:\app\install\cocos\cocos-cli
npm install --global node-gyp
npm run init
npm install
npm run build
npm link

完成后我先检查了一遍版本、命令和实际执行文件：

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

这里有个小坑。README 里写到的命令，不一定都出现在当前 Alpha 版本中。我本机的 cocos -h 只有 build、create、make、preview、run、start-mcp-server 和 upload。最后还是要相信本机帮助，不要根据 README 猜命令。

如果安装时报 EPERM，我会先看安装目录和项目目录是否可写，再检查有没有进程占用文件。Cocos 会在项目里生成 library 和 temp，这些目录本来也不该提交到 Git。

让 Codex 连上 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

然后看一下端口：

Test-NetConnection 127.0.0.1 -Port 9527

端口正常以后，我在仓库的 .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，没必要因为 9527 端口没启动就让整个 Codex 会话不可用。

配置完成不代表真的连上了。我让 Codex 查询了一次当前场景和项目资源，拿到 Creator 里的真实数据以后，才算确认连接正常。

连上以后到底能做什么

这版 MCP 一共暴露了 68 个工具。数量看起来很多，其实按我自己的使用习惯，主要就是几类。

一类是场景和节点操作。Codex 可以打开、查询和保存场景，也可以创建节点、调整层级、修改属性。另一类是组件和 Prefab，它可以给节点挂组件，设置组件属性，或者应用、还原 Prefab 修改。资源导入、移动、重命名和重新导入也有对应工具。

我最常用的还有日志查询。改完脚本或资源后，让 Creator 重新导入，再看最新的错误和警告，比只跑一次 TypeScript 检查更接近 Creator 的真实状态。

MCP 里也有一组 Builder 工具，能构建、运行和上传。它们确实存在，但我后来明确禁止 Codex 调用。这不是遗漏，后面会讲原因。

我发现 Codex 一直在验证错误的东西

最开始，Codex 创建了一个组件脚本，准备在生命周期方法里动态生成界面。脚本文件是有了，它便开始关注构建和浏览器预览。

我越看越觉得不对。打开 Creator 的场景，层级管理器里没有新节点，也没有任何组件挂载。一个空场景，就算构建十次也不会凭空变成已经完成的界面。

Cocos Creator 的场景是序列化资产。Codex 写完脚本以后，还应该通过 MCP 打开目标场景，查询现有节点，把入口组件挂到真实节点上，设置属性并保存场景。保存后再查询一次，确认这些内容确实进了场景文件。

现在我会先让它回答几个很具体的问题：当前打开的是哪个场景，入口节点在哪里，组件挂在什么节点上，场景保存了吗。只有这些信息对得上，才继续看脚本检查。

界面可以在运行时动态创建，但场景里至少要留下一个明确的入口节点和已经挂载的组件。否则我打开 Creator 时根本看不出它做了什么，也无法判断这段代码会不会执行。

我想要的“检查”不是构建

接下来我问的是 Cocos 有没有快速检查方式。Codex 又把注意力放到了构建上，但我想要的只是尽快发现语法、脚本导入和 Creator 资源错误。

当前版本的 Cocos CLI 没有独立的 check 命令。我最后在项目的 package.json 里加了自己的快捷命令：

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

平时先运行：

npm run check

这一步只检查 TypeScript。接着我让 Codex 通过 MCP 刷新或重新导入改过的资源，再读取 Creator 最新的 error 和 warn 日志。Creator 自己的资源导入和脚本编译问题，不一定会出现在 tsc --noEmit 的结果里。

日志也要注意时间。Creator 可能留着之前的错误，如果不看时间，Codex 很容易拿一条旧日志继续排查。必要时先清理日志，再执行这次刷新。

到这里就够了。为了做一次快速检查而执行完整构建，我觉得没有意义。

builder_run 给了我一个错误的预览地址

为了弄清 Builder 工具的行为，我让 Codex 实际调用过一次 builder_run。它按照工具文档，把已经构建好的目录传了进去：

project://build/web-desktop

调用本身返回成功，还给出了一个预览地址：

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

这个地址访问不了，返回的是 404。实际能打开的是：

http://localhost:9527/

这次结果让我确认了一件事：工具返回 200，只能说明调用结束了，不能说明它给出的预览地址正确。更不能据此判断场景、画面和交互已经通过验证。

后面 Codex 还尝试用 Python 启动静态服务器来预览。我不需要这条绕路。Cocos Creator 自己就能运行和预览，真正要看的也是 Creator 里的结果。

最后我把规则写死了

经过这几次来回，我在项目规则里明确写下：Codex 不得调用任何 Cocos MCP builder_* 工具，也不能执行 Cocos CLI 的 build、make、preview、run 和 upload。

它可以查询和修改场景，创建节点，挂载组件，处理资源。改完以后跑 TypeScript 检查，通过 MCP 刷新资源，再看 Creator 日志。做到这里就停。

构建和运行由我自己在 Cocos Creator 里完成。画面是否正常、组件是否真的工作、交互有没有问题，这些都要亲眼看过才能确认。Codex 从一个返回码和 URL 推断不出来。

现在我使用这套 MCP 时，流程已经简单很多：先确认服务和场景，再让 Codex 修改；修改完成后保存场景，重新查询节点和组件；最后跑静态检查，刷新资源并读取日志。剩下的事情我自己打开 Creator 验证。

这才是我想要的配合方式。Codex 负责那些可以明确读取和检查的工作，Creator 负责真实运行，我负责最终判断。