cocos-mcp
cocos 3.8.4 2d能写shader的mcp，报错他能自己改
https://www.bilibili.com/video/BV12CGG6yE6P/?vd_source=fcaf9af78115af41b55fe1f11da57759视频演示

https://github.com/1327485531/cocos-mcp
github

cocos-mcp
cocos 3.8.4 2d能写shader的mcp，报错他能自己改

cocos-mcp
让 AI 编程助手（Claude Code / Cursor 等）直接操控 Cocos Creator 编辑器的 MCP 插件。 你在对话里下指令，AI 就能读场景、建节点、改材质、调 shader 参数、运行预览——就像多了一双能直接操作编辑器的手。

你（中文对话） Claude Code 等客户端 cocos-mcp server Cocos Creator 编辑器
“把 Canvas/Water 的水面调更蓝” ──▶ 调用 cocos-creator 工具 ──▶ dist/index.js(stdio) ──▶ 扩展内的 WebSocket 桥(38633)
└▶ Editor.Message API
MCP server：server/，一个 Node.js 程序，向 AI 暴露 39 个工具（create_effect、set_material_property、create_node、preview_game 等）。
编辑器扩展：extension/，装进 Cocos Creator 后，在编辑器主进程里跑一个 WebSocket 桥（默认端口 38633），把命令翻译成编辑器 API 调用。
功能特性
读/列场景与资源，解析场景节点树与组件
创建 / 修改 / 删除节点，加组件、设属性
创建 .effect shader、.mtl 材质，静态校验 shader 错误（UBO 对齐、GLSL 保留字、YAML 语法等）
实时读/改场景中材质的属性（改完自动应用到所有引用它的 Sprite）
一键运行 / 停止 / 重启游戏预览，查编辑器控制台日志，测场景实时帧率
专门为"写 shader"优化的闭环：改 effect → 校验 → 重编译 → 同步材质 → 热更新回场景
前置要求
Node.js 16+（用于跑 MCP server）—— https://nodejs.org
Cocos Creator 3.8+ 任意项目
一个 MCP 客户端：Claude Code（推荐）、Cursor、或其他支持 stdio MCP 的工具
快速安装（一键）
在 Windows 上双击 install-gui.bat（或在命令行运行）：

install-gui.bat
按提示：

确认 CocosCreator.exe 路径（会自动探测常见安装位置）
输入要接入的 Cocos 工程目录
选择扩展装到全局（所有工程可用）还是当前工程
询问是否写入 Claude Code 全局配置（写入前会先备份 ~/.claude.json）
安装完完全退出并重启 Claude Code，即可在会话里看到 cocos-creator 工具。

静默安装：install.bat --editor “C:…\CocosCreator.exe” --project “C:\mygame” --ext-global --write-claude 预览行为不真正执行：node tools\install.cjs --dry-run …

手动安装

1. 装编辑器扩展
   把 extension/ 整个文件夹拷到下面任一位置：

全局（所有工程可用）： %USERPROFILE%.CocosCreator\extensions\cocos-mcp-bridge
项目级（仅某个工程）： <工程目录>\extensions\cocos-mcp-bridge
extension/ 自带编译产物和 node_modules，无需自己安装依赖。

装完后需要重启 Cocos Creator 才会加载扩展。

2. 配置 MCP server
   给 server 指定 CocosCreator.exe 和工程路径，三选一：

a) 生成配置文件（推荐）：在 server/ 下新建 cocos-mcp.config.json：

{
“projectPath”: “C:/your/cocos/project”,
“editorPath”: “C:/ProgramData/cocos/editors/Creator/3.8.4/CocosCreator.exe”,
“bridgePort”: 38633,
“autoLaunch”: true
}
b) 环境变量（适合写在 MCP 客户端配置里）：

变量 说明
COCOS_PROJECT_PATH Cocos 工程目录（含 assets/）
COCOS_EDITOR_PATH CocosCreator.exe 完整路径
COCOS_BRIDGE_PORT 桥端口，默认 38633
COCOS_AUTO_LAUNCH 编辑器没开时是否自动拉起，true/false
c) 自动探测：在工程目录里启动 server，会自动识别工程和常见安装位置的编辑器。

3. 把 MCP 配置给客户端
   参考 mcp.json.example，在 Claude Code 的 ~/.claude.json（mcpServers 字段）或 claude mcp add 里配置：

{
“mcpServers”: {
“cocos-creator”: {
“command”: “node”,
“args”: [“C:/你的路径/cocos-mcp/server/dist/index.js”],
“env”: {
“COCOS_PROJECT_PATH”: “C:/你的Cocos工程目录”,
“COCOS_EDITOR_PATH”: “C:/ProgramData/cocos/editors/Creator/3.8.4/CocosCreator.exe”
}
}
}
}
4. 使用
打开 Cocos Creator（扩展会自动起桥，端口 38633）
打开 Claude Code，直接说：
用 cocos-creator 列一下当前场景有哪些节点
给 Canvas/Water 的水面材质加一层流动波纹
创建一个演示 Sprite 挂上 assets/card-rainbow.mtl
卸载
删除扩展目录（全局 %USERPROFILE%.CocosCreator\extensions\cocos-mcp-bridge，或工程 extensions\cocos-mcp-bridge），重启 Cocos Creator
从 ~/.claude.json 的 mcpServers 删除 cocos-creator 条目（或 claude mcp remove cocos-creator）
删除 server/、tools/ 目录即可
常见问题
Q：~/.claude.json 备份在哪？ A：安装器写入前会把原文件备份成 ~/.claude.json.bak-mcp。

Q：改完扩展源码不生效？ A：Cocos 扩展源码改了必须重启 Cocos Creator。server 端改代码后 cd server && npm run build，然后重启 Claude Code（或对已运行会话调用 server_reload 工具热重载）。

Q：端口 38633 被占用 / 编辑器连不上？ A：确认编辑器里扩展已加载（菜单 “扩展 → 扩展管理器” 里能看到 cocos-mcp-bridge），且只开了一个编辑器实例。改端口需同时改 config 与 bridgePort。

Q：工具一直报 bridge not connected？ A：编辑器没打开，或扩展还没加载完。COCOS_AUTO_LAUNCH=true 时 server 会自动拉起编辑器，等几秒重试即可。

Q：预览时场景没生效（用的还是旧 shader）？ A：改完 effect 后调用工具 reload_material / update_effect / preview_reload_browser 强制刷新缓存。

二次开发 / 构建
server/src/：MCP 工具实现（tools.ts）、编辑器桥客户端（bridge.ts）、shader 静态分析（shader-analyzer.ts）。改完 cd server && npm run build。
发布包的 server/node_modules 是生产裁剪版（npm prune --production 已去掉 typescript/@types 等编译期依赖，包体积 70M→19M）。要重新编译请先 cd server && npm install 恢复 devDependencies。
extension/src/：编辑器内 WebSocket 桥。改完 cd extension && npm run build，并重启编辑器。
测试工具：tools/ 下有 install.cjs（安装器）、selfcheck（安装时自检）等。
reference-effects/：参考 shader 库（8 个代表 effect：像素爆炸 / 装备流光 / 卡通火焰 / 水面加载条 / 雨玻璃 / 闪电 / 卡牌彩虹 / 涟漪）。安装器会自动拷进工程 assets/refs/，让 AI 换工程也有本地参考（已有同名文件不覆盖）。
许可证
MIT