Cocos Creator MCP

MCP (Model Context Protocol) server extension for Cocos Creator 3.8+.

AI assistants like Claude can control Cocos Creator editor through this extension — creating nodes, editing scenes, managing prefabs, building projects, and more.

Features (v2.0.0)

• ~73 Tools organized as category_action patterns — token-efficient for LLM clients
• 12 MCP Resources (cocos://) — read-only data exposed via URI, separate from tools
• execute_editor_script — escape hatch for arbitrary editor-side JavaScript (async/await supported)
• read_console — unified Editor/Scene/Game console reader (captures compile errors, runtime errors, console.log)
• Transparent value references — db:// asset paths, {path}/{guid} objects, enum names, cc.Vec3/Color/Size plain objects all auto-resolved
• Streamable HTTP (SSE) — Native MCP transport
• JSON-RPC 2.0 — Standard MCP protocol
• Prefab Property Persistence — Component properties preserved across saves
• Preview in Editor / Screenshot / Video Recording / Game Command Control
• Client Scripts — Drop-in TypeScript files for game preview integration (client/)
• Auto Start / Tool Call Logging / i18n (en/ja/zh)
• 357+ Regression Test Assertions — all real-invocation + side-effect verification

Quick Start

1. Install

Copy or symlink this extension into your Cocos Creator project’s extensions/ directory:

# 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. Build

cd cocos-creator-mcp
npm install
npm run build

3. Enable in Cocos Creator

1. Open your project in Cocos Creator
2. Go to Extension > Extension Manager
3. Enable Cocos Creator MCP
4. Open the panel: Extension > Cocos Creator MCP > Open Panel
5. Click Start Server (or set autoStart: true in config)

4. Connect from Claude Code

Pick one of the two transports below.

Option A — stdio bridge (recommended for Claude Code VSCode extension)

The Claude Code VSCode extension currently has a bug where it unconditionally tries OAuth Dynamic Client Registration for HTTP-type MCP servers and fails with SDK auth failed (see upstream issues #26917, #38102, #29697). To avoid it entirely, use the bundled stdio bridge. It speaks JSON-RPC on stdin/stdout and forwards to the HTTP server internally.

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

Optional env var: COCOS_MCP_URL (default http://127.0.0.1:3000/mcp).

Option B — direct HTTP

Works with Claude Code CLI, Cursor, Cline, and other clients that don’t force OAuth on HTTP MCP. The server ships minimal dummy OAuth endpoints (/.well-known/oauth-*, /oauth/register|authorize|token) so OAuth-requiring clients can still complete a pro-forma flow on localhost.

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

The dummy OAuth endpoints will be removed once upstream issues (#26917, #38102) are resolved or real authentication is introduced.

5. Verify

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

Available Tools (~64)

The post-v2.0.0 layout. Each category is consolidated into a single tool that switches behavior via the category_action pattern (a 61% reduction from v1’s 166 tools).

Available Resources (12)

MCP resources are read-only data sources exposed via URI, separate from tools. Listed via resources/list and resources/templates/list, fetched via resources/read.

Client Scripts

The client/ directory contains TypeScript files for runtime communication between the game preview and the MCP server. Since the extension is installed in extensions/, these files can be imported directly — no copying needed.

McpConsoleCapture

Captures console.log/warn/error from the game preview and sends them to the MCP server.

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

McpDebugClient

Enables AI-driven game control: screenshots, node clicking, and custom commands.

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 };
        },
    },
});

Built-in commands (no setup needed):

• screenshot — Capture game screen via RenderTexture
• click — Click a node by name

Custom commands (project-specific):

• Register any handler via customCommands option
• Called via debug_game_command MCP tool

Both scripts silently ignore when the MCP server is not running, so they are safe to leave in development builds.

Console Log Capture (Details)

read_console captures logs from three sources (editor / scene / game):

Scene Process Logs (automatic)

Console output from scene scripts (console.log/warn/error in the scene renderer process) is automatically captured. No setup required.

Game Preview Logs (opt-in)

Game code runs in a browser during preview, which is a separate process. To capture game preview logs, your game code needs to send logs to the MCP server’s /log endpoint.

Setup:

Add a console capture script to your game project:

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 format:

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

Editor / scene / game entries are merged chronologically when retrieved via read_console(action="get"). Each entry includes a source field ("editor" / "scene" / "game"). Filter via types: ["error", "warn"], sources: ["scene"], count, since, search, or includeStacktrace. Clear with read_console(action="clear").

Configuration

Settings are stored in {project}/settings/cocos-creator-mcp.json:

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

Testing

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

Version History

• v0.1 — MCP server + scene/node tools (13 tools)
• v0.5 — Component, prefab, project, debug tools (27 tools)
• v1.0 — Full tool coverage (145 tools, 13 categories, 224 test assertions)
• v1.1 — Console log capture (scene process auto-capture + game preview via /log endpoint)
• v1.2 — AI autonomous development: Preview in Editor, screenshot capture, game command control, code cache clear, scene save fix. Client scripts for game preview integration (client/)
• v1.3 — scene:set-property for prefab save support, prefab_create overwrite guard, param alias (component → componentType)
• v1.5 — prefab_create_and_replace, batch set_property, prefab_open
• v1.6 — debug_batch_screenshot, widget support in create_tree, component_query_enum, server_check_code_sync
• v1.8.0 — Preview Recorder panel: debug_record_start / debug_record_stop (MediaRecorder via canvas.captureStream, MP4/WebM, quality presets)
• v1.8.1 — Fix: component_set_property cc.Asset references (cc.Font etc.) falling back to cc.Node when type is unspecified
• v1.8.2 — Preview Recorder: screenshot button (webp/png toggle, max width), section-based UI layout
• v1.9.0 — Preview Recorder auto-archive of old recordings + preflight “preview not running” check
• v1.10.0 — scene_create asset-db fallback, stringified args preventive validation, test coverage expansion
• v1.11.0 — HTTP MCP OAuth workaround (stdio bridge + dummy OAuth endpoints for Claude Code VSCode upstream bug) + dialog prevention for scene switching tools (force param, ensureSceneSafeToSwitch, safeSaveScene) + regression tests for both
• v1.12.0 — Prefab authoring efficiency: component_auto_bind (auto-match @property fields to node names), debug_wait_compile (wait for TS compile to finish), prefab_create_from_spec (create node tree + auto-bind + prefab_create in one call)
• v1.13.0 — nodeName parameter on component/get_components/auto_bind (no UUID required), screenshot auto-return option on component_set_property / node_set_layout, node_set_layout unified tool (UITransform + Widget + color/opacity in one call), dialog auto-response for untitled+dirty scenes, shared screenshot / node-resolve utilities
• v1.14.0 — Widget _alignFlags auto-recalc bug fix: setProperty / setProperties / node_set_layout now re-query isAlign* values from scene and rebuild _alignFlags bitmask after isAlign updates (Editor bug where bitmask was not updated automatically, causing prefabs to save with _alignFlags: 45 stuck state). Also node_create component addition now waits for editor reflection (waitForComponent) to fix flaky tests
• v2.0.0 (BREAKING) — Major tool topology refactor: 166 → ~64 tools (-61%).
  • New: read_console (Editor + Scene + Game console with type/source filters, compile error detection via project.log fallback), execute_editor_script (escape hatch for arbitrary editor JS), 12 MCP Resources (cocos://scene/*, cocos://node/{uuid}, cocos://component/{uuid}, cocos://prefab/*, cocos://project/*, cocos://editor/info, cocos://asset/{uuid}).
  • Enhanced component_set_property: transparent value references — db://... asset paths, {path} / {guid} objects, enum names, cc.Vec3/Vec2/Vec4/Color/Size plain objects all auto-resolved.
  • Aggregated tools into category_action patterns: scene_manage, scene_clipboard, scene_undo, scene_array, scene_reset, scene_view_*, node_manage, component_manage, prefab_edit, asset_manage, asset_query, view_gizmo/settings/camera, refimage_manage/set/query, preferences_manage, builder_manage, server_status, debug_logs/extension/record.
  • Fixed prefab_create_from_spec asset-ref serialization bug — properties are now reapplied via Editor API after node tree build, so asset refs serialize as {__uuid__, __expectedType__} correctly. The post-processing workaround is no longer needed.
  • Removed: read-only tools that have resource equivalents (scene_query_node, scene_query_node_tree, scene_query_component, component_get_components, component_get_info, prefab_list, prefab_get_info, project_get_info, project_get_engine_info, debug_get_editor_info) and v2 deprecated (debug_get_console_logs, debug_clear_console).
  • See MIGRATION.md for the v1 → v2 mapping table. See CHANGELOG.md for the full change log.

Development

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

After building, reload the extension in Cocos Creator:

• Extension Manager — disable then re-enable
• Developer > Reload — reloads main process
• Full restart — required for scene script or new category changes

Requirements

• Cocos Creator 3.8+
• Node.js 18+

Value Reference Forms (v2.0.0)

component_set_property accepts multiple convenient forms for asset references, node references, enums, and structured value types. The MCP server resolves each to the correct Editor dump format internally.

Asset references

// All four forms are equivalent for a SpriteFrame field:
{ "value": "" }                                 // raw UUID
{ "value": "db://assets/textures/foo.png" }           // asset path string
{ "value": { "path": "db://assets/textures/foo.png" } }  // {path}
{ "value": { "guid": "" } }                     // {guid}

Node / component references

// Resolves to a node by descendant path under the active scene root:
{ "value": "@path:Canvas/Background" }

// Or pass a node UUID directly — the property type is inferred from the schema:
{ "value": "" }

Enum values

// Name (v2.0.0) — looked up against the property's enumList:
{ "value": "HORIZONTAL" }

// Numeric (still supported):
{ "value": 1 }

Structured value types (v2.0.0)

// cc.Vec3 / cc.Vec2 / cc.Vec4 — pass plain coordinates:
{ "value": { "x": 100, "y": 50, "z": 0 } }

// cc.Color — RGBA in 0-255 range:
{ "value": { "r": 255, "g": 0, "b": 0, "a": 255 } }

// cc.Size — width/height (or x/y) are both accepted:
{ "value": { "width": 200, "height": 100 } }

These also work inside prefab_create_from_spec’s spec.properties because the asset-ref serialization bug was fixed in v2.0.0 (properties are now reapplied via the Editor API after the node tree is built).

Known Limitations

• scene_create: Does not work on Cocos Creator 3.8.x because the underlying scene:new-scene Editor message is not exposed on that version. As a workaround, create the .scene JSON file directly under db://assets/ and call project_refresh_assets so the editor picks it up. See #13 for details.

• prefab_create_from_spec — asset refs are saved as raw UUID strings (fixed in v2.0.0) — Properties in spec.properties are now reapplied via the Editor API (component_set_property) after buildNodeTree completes, so asset refs serialize as {__uuid__, __expectedType__} correctly. The old workaround of post-processing .prefab files is no longer needed.

License

MIT