让AI替代Cocos开发者篇(一)

一句话：装上这个编辑器插件，Claude、Cursor 这类 AI 就能直接读写你的 Cocos 工程——查场景、改节点、操作资源、看控制台，甚至能看到游戏在浏览器预览里跑出来的实时日志。

一、背景：AI 能写代码，但够不到你的编辑器

这一两年大家都在用 AI 写游戏逻辑，但有个尴尬的断层：AI 看不见你的编辑器。

它不知道你当前打开的是哪个场景、节点树长什么样；
改完脚本有没有编译报错，它得靠你截图复制；
想让它帮忙调一个节点的位置、换个组件属性，只能口述，它再告诉你手动点哪里；
游戏跑起来报了个错，它更是两眼一抹黑——因为日志在浏览器预览页里，编辑器进程根本拿不到。

MCP（Model Context Protocol）就是用来打通这层的：它是一套让 AI 调用外部工具的标准协议。cocos-mcp 把 Cocos Creator 编辑器包装成一个 MCP 工具服务，于是任何支持 MCP 的 AI 客户端都能直接驱动你的编辑器。

二、这是什么

cocos-mcp 是一个 Cocos Creator 编辑器扩展，分两个版本：

cocos-mcp-2x
—— 适配 Cocos Creator 2.4.x（在 2.4.15 上验证）
cocos-mcp-3x
—— 适配 Cocos Creator 3.7 ~ 3.8.x

两个版本共用同一套 Python MCP server 和通信协议，区别只在于调用的编辑器 API 不同。插件是自包含的——Python server 已经打包在插件的 ./server 目录里，扩展本身没有任何 npm 依赖、零构建步骤，丢进工程加载即可。

工作原理（一张图）

AI 客户端 (Claude Desktop / Cursor / 任意 MCP 客户端) │ stdio / http ▼Python FastMCP server ── server/src/main.py │ WebSocket 桥 127.0.0.1:6020/cocosmcp ▼Cocos Creator 扩展 ── main.js（作为 WS 客户端拨入） │ ├─ 资源数据库 / 场景 API：增删查改 └─ 场景脚本：通过 cc 引擎操作运行时节点树

一个小巧思：Python 端是 WebSocket 服务端，编辑器扩展是客户端，靠面板上一个「Connect」按钮拨进去。所以你只需要在编辑器里点一下连接，全程不用折腾命令行。

三、核心功能

插件向 AI 暴露了这几个工具：

工具	作用
`get_project_info`	工程路径、assets 根、编辑器版本、场景列表、可用命令
`manage_scene`	列出 / 打开 / 保存 / 查询当前场景
`manage_node`	检视或修改当前场景里的节点（位置、属性、组件等，多数按 `uuid`）
`manage_asset`	通过资源数据库检视和操作 `assets/` 下的资源
`read_console`	读取 / 清空日志缓冲（同时含编辑器日志和游戏运行时日志）
`execute_script`	在编辑器主上下文或场景上下文执行任意 JS（强力逃生舱）

亮点：让 AI 看到「游戏运行时」的日志

这是 v0.4.0 新加的能力，也是最实用的一个。

编辑器进程看不到游戏在浏览器预览里跑出来的 cc.log / console.*。插件面板里开启「浏览器预览日志捕获」后：

扩展在本地起一个轻量 HTTP 接收器（端口 = 桥端口 + 1，默认 6021）；
往项目的预览模板里就地注入一段上报脚本，把浏览器里游戏的每条日志回传；
日志和编辑器日志落进同一个环形缓冲，标记 source: "runtime"。

于是你可以直接对 AI 说「看下游戏现在的报错」，它就会调用 read_console(sources=["runtime"], levels=["error"]) 把游戏里的错误捞出来分析——不用你再去浏览器 F12 复制粘贴。

小贴士：读 Cocos 游戏日志请认准 read_console 这个工具，别让 AI 跑去用通用的浏览器自动化工具——那种工具够不到编辑器的预览标签页。

四、使用攻略

1. 安装插件

把插件文件夹放进你工程对应的扩展目录：

2.x
：放到 <工程>/packages/cocos-mcp-2x/
3.x
：放到 <工程>/extensions/cocos-mcp-3x/

重启编辑器（或扩展管理里刷新），菜单栏会出现 Cocos MCP → Open Panel。

2. 首次使用：建 Python 环境

需要 Python 3.10+。在插件的 server 目录里建一个虚拟环境：

cd cocos-mcp-3x/serverpython -m venv .venv.venv\Scripts\python -m pip install -e .

国内网络 pip 容易超时，可以加清华镜像：.venv\Scripts\python -m pip install -e . -i https://pypi.tuna.tsinghua.edu.cn/simple

面板上会实时显示 python: found / NOT FOUND，找不到时还会把上面这条命令直接提示给你。

3. 在面板里启动

打开面板 Cocos MCP → Open Panel：

Server dir 留空 = 用插件自带的 ./server（推荐）；
点 Start Server，看到 python: found 即就绪；
点 Connect，出现绿点表示桥已连上。

默认端口：桥 6020、HTTP 8765（3.x）/ 8799（2.x）。被占用就在面板里改一下再 Start，Server URL 会自动跟着同步。

4. 配置你的 AI 客户端

server 入口是 server/src/main.py，支持 stdio（客户端默认）和 http：

cd cocos-mcp-3x/server/srcpython -m main --transport stdio# Claude Desktop / Cursorpython -m main --transport http --http-port 8765# 手动测试

在 Claude Desktop / Cursor 的 MCP 配置里指向这个 server 即可。连上后，AI 的工具列表里就会出现上面那几个工具。

5. 实战示例

连好之后，你可以直接这样对 AI 说：

「当前打开的是哪个场景？把根节点树列出来。」
「把 Btn_Start 节点的 x 改成 200，然后保存场景。」
「我刚改了脚本，有没有编译报错？」 → 它会调 read_console(sources=["editor"])
「游戏跑起来报了个错，帮我抓一下。」 → 它会调 read_console(sources=["runtime"], levels=["error"]) 并定位

6. 开启运行时日志捕获（可选但强烈推荐）

面板里点「开启捕获」→ 重启一次编辑器（引擎会缓存预览模板）→ 预览时选「Browser」运行。之后游戏里的日志就能被 read_console 读到了。关闭时会干净地把注入内容移除，不破坏你自己的预览模板。

五、2.x 与 3.x 怎么选

	cocos-mcp-2x	cocos-mcp-3x
适配引擎	Cocos Creator 2.4.x	Cocos Creator 3.7 ~ 3.8.x
安装目录	`packages/`	`extensions/`
场景文件	`.fire`	`.scene`
默认 HTTP 端口	8799	8765
运行时日志	✅	✅

按你工程的引擎版本选对应的就行，两边功能对齐。

六、仓库地址 & 求个 Star ⭐

项目开源，两个版本分别在：

Cocos 2.x
：https://github.com/shiliyu1991-lang/cocos-mcp-2x
Cocos 3.x
：https://github.com/shiliyu1991-lang/cocos-mcp-3x

如果它帮你省了事，点个 Star 是对作者最大的鼓励 🙏。有问题、想要的功能，欢迎提 Issue，一起把 AI + Cocos 的工作流打磨得更顺手。