Cocos Creator Mcp

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).

Scene (12)

• scene_manage(open/save/close/list/current/hierarchy)
• scene_clipboard(copy/paste/cut)
• scene_undo(snapshot/snapshot_abort/begin/end/cancel)
• scene_array(move/remove)
• scene_reset(transform/property/component/restore_prefab)
• scene_query(dirty/ready/classes/components/component_has_script/nodes_by_asset/scene_bounds)
• scene_create, scene_save_as, scene_set_parent, scene_soft_reload
• scene_execute_script, scene_execute_component_method

View (3) — Scene view (gizmo / settings / camera)

• view_gizmo(set_tool|get_tool|set_pivot|get_pivot|set_coordinate|get_coordinate)
• view_settings(set_mode|get_mode|set_grid|get_grid|set_icon3d|get_icon3d|set_icon_size|get_icon_size|status|reset)
• view_camera(focus_on_nodes|align_with_view|align_view_with_node)

Note: Editor APIs not supported on 3.8.x degrade to a graceful no-op (returning a note).

Node (10)

• node_manage(create/delete/duplicate/move)
• node_create_tree — build a node hierarchy in a single call
• node_set_property, node_set_transform, node_set_active, node_set_layout
• node_get_info, node_find_by_name, node_get_all, node_detect_type

Component (3)

• component_manage(add/remove/available/enum)
• component_set_property — Reflection-based. Supports asset path / {path} / {guid} / enum name / cc.Vec3/Color/Size plain object forms (see Value Reference Forms section)
• component_auto_bind — auto-match @property fields to descendant nodes by name

Prefab (7)

• prefab_edit(open/close)
• prefab_create(mode: simple/replace/from_spec) — extract / extract-and-replace / build-from-spec all unified
• prefab_instantiate, prefab_update, prefab_revert, prefab_duplicate, prefab_validate

Asset (2)

• asset_manage(create/delete/move/copy/save/reimport/import/save_meta/open_external)
• asset_query(path/uuid/url/details/dependencies/users/missing/ready/generate_url)

Project (6)

• project_refresh_assets, project_get_asset_info, project_find_asset
• project_get_settings, project_set_settings, project_query_scripts

For project name / path / engine info, use the cocos://project/* resources.

Debug (15)

Console / scripts: read_console, execute_editor_script, debug_execute_script, debug_list_messages. Logs / extension / record: debug_logs(get/search/info), debug_extension(list/info/reload), debug_record(start/stop). Editor / preview: debug_validate_scene, debug_clear_code_cache, debug_wait_compile, debug_query_devices, debug_open_url, debug_preview, debug_screenshot(target: window/pages), debug_game_command.

Preferences / Builder / Server (3)

• preferences_manage(get/set/get_all/reset)
• builder_manage(open_panel/get_settings/query_tasks/run_preview/stop_preview)
• server_status(get/ips/port/build_hash/connectivity/interfaces/code_sync)

Reference Image (3)

• refimage_manage(add/remove/clear_all/switch/refresh)
• refimage_set(position/scale/opacity)
• refimage_query(list/current)

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.

| URI | Returns | |---|---| | cocos://scene/current | Current scene name + uuid | | cocos://scene/list | All .scene files | | cocos://scene/hierarchy | Current scene's node tree | | cocos://node/{uuid} | Full property dump of a node | | cocos://node/{uuid}/components | Component summary list | | cocos://component/{uuid} | Full property dump of a component | | cocos://prefab/list | All prefabs | | cocos://prefab/{uuid} | Prefab asset info | | cocos://project/info | Project name + path | | cocos://project/engine | Engine version + path | | cocos://editor/info | Cocos Creator editor info | | cocos://asset/{uuid} | Asset details |

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
}

| Option | Default | Description | |--------|---------|-------------| | port | 3000 | HTTP server port | | autoStart | false | Start server automatically when extension loads |

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/getcomponents/autobind (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,

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: harady
• Source: harady/cocos-creator-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.