Cocos Creator MCP

Cocos创建者MCP

MCP（模型上下文协议） Cocos Creator 3.8+的服务器扩展。

像Claude这样的人工智能助手可以通过这个扩展来控制Cocos Creator编辑器——创建节点、编辑场景、管理预制件、构建项目等等。

特性

• 164工具 跨越13个类别——全面的编辑器自动化
• 流式HTTP（SSE） --原生支持MCP的流式HTTP传输
• JSON-RPC 2.0 --符合标准MCP协议
• 预制性能持久性 --保存预制件时，组件属性得到正确保留
• 在编辑器中预览 --以编程方式启动编辑器预览（无需手动点击按钮）
• 电脑屏幕截图工具 --捕获编辑器窗口和游戏预览屏幕截图（WebP/PNG）
• 视频录制 --通过预览录制器面板将游戏预览画布录制为视频（MP4/WebM）
• 游戏命令控制 --发送命令以运行游戏预览（截图、点击、导航、状态、检查）
• 客户端脚本 --插入TypeScript文件以集成游戏预览(client/)
• 自动启动 --当扩展加载时，服务器会自动启动
• 工具调用记录 --所有工具调用都记录了调试时间
• UUID验证 --输入验证助手以获得更好的错误消息
• 国际化 --英语、日语、中文
• 回归测试 --涵盖核心工具流的200多个断言

快速开始

1.安装

将此扩展复制或符号链接到您的Cocos Creator项目中 extensions/ 目录：

# Windows (Junction — no admin required)
mklink /J "your-project\extensions\cocos-creator-mcp" "path\to\cocos-creator-mcp"

# macOS / Linux
ln -s /path/to/cocos-creator-mcp your-project/extensions/cocos-creator-mcp

2.建造

cd cocos-creator-mcp
npm install
npm run build

3.在Cocos Creator中启用

1. 在Cocos Creator中打开您的项目
2. 首选 扩展>扩展管理器
3. 启用 Cocos创建者MCP
4. 打开面板： 扩展>Cocos Creator MCP>打开面板
5. 点击 启动服务器 （或设置 autoStart: true 在配置中）

4.从克劳德代码连接

从下面两种运输方式中选择一种。

选项A--stdio桥（建议用于Claude Code VSCode扩展）

Claude Code VSCode扩展目前有一个错误，它无条件地 尝试为HTTP类型的MCP服务器进行OAuth动态客户端注册，但失败 和 SDK auth failed （见上游问题 #26917, #38102, #29697). 为了完全避免这种情况，请使用捆绑的stdio网桥。它在上讲JSON-RPC stdin/stdout并在内部转发到HTTP服务器。

{
  "mcpServers": {
    "cocos-creator-mcp": {
      "command": "node",
      "args": [
        "/cocos-creator-mcp/client/stdio-bridge.js"
      ]
    }
  }
}

可选环境变量： COCOS_MCP_URL （默认值 http://127.0.0.1:3000/mcp).

选项B——直接HTTP

适用于Claude Code CLI、Cursor、Cline和其他不强制执行的客户端 HTTP MCP上的OAuth。服务器提供最少的虚拟OAuth端点 (/.well-known/oauth-*, /oauth/register|authorize|token)因此OAuth要求 客户端仍然可以在本地主机上完成形式流。

{
  "mcpServers": {
    "cocos-creator-mcp": {
      "type": "http",
      "url": "http://127.0.0.1:3000/mcp"
    }
  }
}

一旦上游问题出现，虚拟OAuth端点将被删除 (#26917, #38102) 或者引入真正的身份验证。

5.验证

curl http://127.0.0.1:3000/health
# {"status":"ok","tools":164}

可用工具（164）

Scene (6) — Scene lifecycle and hierarchy

Scene Advanced (30) — Undo, clipboard, queries, property manipulation

Scene View (19) — Gizmo, camera, grid, viewport

Node (14) — Create, edit, move, delete nodes

Component (8) — Add, remove, configure components

Prefab (12) — Prefab lifecycle and validation

Asset (18) — CRUD, queries, metadata, dependencies

Project (8) — Project info, settings, engine

Preferences (4) — Editor preferences

Debug (22) — Editor info, logs, preview, screenshots, recording, game control

Server (7) — Editor server and network

Builder (5) — Build and preview

Reference Image (11) — Scene overlay images

客户端脚本

这 client/ 目录包含用于游戏预览和MCP服务器之间运行时通信的TypeScript文件。由于扩展安装在 extensions/，这些文件可以直接导入，无需复制。

McpConsoleCapture

捕获 console.log/warn/error 并将它们发送到MCP服务器。

// Import from extensions/ (adjust relative path as needed)
import { initMcpConsoleCapture } from "../../extensions/cocos-creator-mcp/client/McpConsoleCapture";
initMcpConsoleCapture();

McpDebugClient

启用AI驱动的游戏控制：屏幕截图、节点点击和自定义命令。

import { initMcpDebugClient } from "../../extensions/cocos-creator-mcp/client/McpDebugClient";

initMcpDebugClient({
    customCommands: {
        // Add project-specific commands
        state: () => ({ success: true, data: { dump: MyDb.dump() } }),
        navigate: async (args) => {
            await MyRouter.goTo(args.page);
            return { success: true };
        },
    },
});

内置命令 （无需设置）：

• screenshot --通过RenderTexture捕获游戏屏幕
• click --按名称单击节点

自定义命令 （项目特定）：

• 通过注册任何处理程序 customCommands 选项
• 通过拨打电话 debug_game_command MCP工具

当MCP服务器未运行时，这两个脚本都会自动忽略，因此它们可以安全地留在开发版本中。

控制台日志捕获（详细信息）

debug_get_console_logs 从两个来源捕获日志：

场景处理日志（自动）

场景脚本的控制台输出(console.log/warn/error 在场景渲染过程中）被自动捕获。无需设置。

游戏预览日志（选择加入）

游戏代码在预览期间在浏览器中运行，这是一个单独的过程。要捕获游戏预览日志，您的游戏代码需要将日志发送到MCP服务器 /log 终点。

设置：

将控制台捕获脚本添加到您的游戏项目中：

const MCP_LOG_URL = "http://127.0.0.1:3000/log";
const FLUSH_INTERVAL = 500;

let buffer: Array = [];

function hook(level: string, original: (...args: any[]) => void) {
    return function (...args: any[]) {
        original.apply(console, args);
        buffer.push({
            timestamp: new Date().toISOString(),
            level,
            message: args.map(a => typeof a === "string" ? a : JSON.stringify(a)).join(" "),
        });
    };
}

console.log = hook("log", console.log);
console.warn = hook("warn", console.warn);
console.error = hook("error", console.error);

setInterval(() => {
    if (buffer.length === 0) return;
    const entries = buffer.splice(0, 50);
    fetch(MCP_LOG_URL, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify(entries),
    }).catch(() => {}); // silently ignore if MCP server is not running
}, FLUSH_INTERVAL);

POST /log 格式：

[
  { "timestamp": "2026-03-26T12:00:00.000Z", "level": "log", "message": "Hello" },
  { "timestamp": "2026-03-26T12:00:01.000Z", "level": "error", "message": "Something failed" }
]

当通过以下方式检索时，场景和游戏日志都会按时间顺序合并 debug_get_console_logs每个日志条目都包含一个 source 现场("scene" 或 "game")以区分起源。

配置

设置存储在 {project}/settings/cocos-creator-mcp.json:

{
  "port": 3000,
  "autoStart": true
}

测试

node test/regression.mjs         # default port 3000
node test/regression.mjs 3001    # custom port

版本历史记录

• v0.1 --MCP服务器+场景/节点工具（13个工具）
• v0.5 --组件、预制件、项目、调试工具（27个工具）
• v1.0 --全工具覆盖（145个工具，13个类别，224个测试断言）
• v1.1 --控制台日志捕获（场景过程自动捕获+游戏预览 /log 端点）
• v1.2 --AI自主开发：在编辑器中预览、截图、游戏命令控制、代码缓存清除、场景保存修复。用于游戏预览集成的客户端脚本(client/)
• v1.3 — scene:set-property 对于prefab保存支持，prefab_create覆盖保护，参数别名(component → componentType)
• v1.5 — prefab_create_and_replace，批次 set_property, prefab_open
• v1.6 — debug_batch_screenshot中的小部件支持 create_tree, component_query_enum, server_check_code_sync
• v1.8.0 --预览记录器面板： debug_record_start / debug_record_stop （通过canvas.captureStream、MP4/WebM、质量预设的MediaRecorder）
• v1.8.1 --修复： component_set_property 未指定类型时，cc.资产引用（cc.Font等）回退到cc.Node
• v1.8.2 --预览录制器：屏幕截图按钮（webp/png切换，最大宽度），基于部分的UI布局
• v1.9.0 --预览记录器自动存档旧记录+飞行前“预览未运行”检查
• v1.10.0 — scene_create 资产数据库回退、字符串化参数预防性验证、测试覆盖率扩展
• v1.11.0 --HTTP MCP OAuth解决方法（stdio桥+克劳德代码VSCode上游错误的虚拟OAuth端点）+场景切换工具的对话预防(force 参数， ensureSceneSafeToSwitch, safeSaveScene)+两者的回归测试
• v1.12.0 --预制创作效率： component_auto_bind （自动匹配 @property 字段到节点名称）， debug_wait_compile （等待TS编译完成）， prefab_create_from_spec （在一次调用中创建节点树+自动绑定+prefab_create）
• v1.13.0 — nodeName 组件/组件/自动绑定上的参数（不需要UUID）， screenshot 自动返回选项打开 component_set_property / node_set_layout, node_set_layout 统一工具（UITransform+Widget+颜色/不透明度在一次调用中），无标题+脏场景的对话框自动响应，共享截图/节点解析实用程序
• v1.14.0 --小工具 _alignFlags 自动重新计算错误修复： setProperty / setProperties / node_set_layout 现在重新查询 isAlign* 场景值和重建 _alignFlags isAlign更新后的位掩码（编辑器错误，位掩码未自动更新，导致序言保存为 _alignFlags: 45 卡住状态）。此外 node_create 组件添加现在等待编辑器反射(waitForComponent)修复片状测试

发展

npm run watch   # Watch mode
npm run build   # One-time build

构建完成后，在Cocos Creator中重新加载扩展：

• 扩展管理器 --禁用然后重新启用
• 开发者>重新加载 --重新加载主进程
• 完全重新启动 --场景脚本或新类别更改所需

需求

• Cocos Creator 3.8+
• Node.js 18+

已知限制

• scene_create：在Cocos Creator 3.8.x上不起作用，因为底层 scene:new-scene 该版本上未显示编辑器消息。作为解决方法，创建 .scene JSON文件直接位于 db://assets/ 并呼叫 project_refresh_assets 所以编辑把它捡了起来。看 #13 了解详情。

• prefab_create_from_spec --资产引用保存为原始UUID字符串:

当规格 properties 包含资产引用，如 cc.Sprite.spriteFrame 或 cc.Prefab 字段，它们被序列化为生成的 .prefab 作为原始UUID字符串，而不是必需的 {__uuid__, __expectedType__} 对象形式。Cocos运行时无法解析它们（例如。 Simple.updateUVs 抛出具有未解析spriteFrame的Sprite的每一帧）。解决方法：对生成的数据进行后处理 .prefab 用于包装资源引用的文件。

修复脚本示例：

  // fix-prefab-asset-refs.js — run after prefab_create_from_spec
  const re = /"_spriteFrame":\s*"([a-f0-9\-]+(?:@[a-z0-9]+)?)"/g;
  content = content.replace(re, (_, uuid) =>
    `"_spriteFrame": { "__uuid__": "${uuid}", "__expectedType__": "cc.SpriteFrame" }`
  );

设置时也适用相同的模式 cc.Prefab 字段通过 component_set_property --忽略值对象表单，并写入原始UUID。直接的 .prefab JSON编辑是可靠的解决方法，直到修复。

许可证

麻省理工学院