cocos-creator-mcp-server skill by reason-machines

Cocos Creator MCP Server Skill

Skill by ara.so — MCP Skills collection.

A comprehensive MCP (Model Context Protocol) server plugin for Cocos Creator 3.8+ that enables AI assistants to interact with the Cocos Creator editor through a standardized protocol. Provides 50 powerful tools covering 99% of editor operations including scenes, nodes, components, prefabs, assets, project management, debugging, and preferences.

Installation

Prerequisites

Cocos Creator 3.8.6 or higher
MCP-compatible client (Claude Desktop, Claude CLI, Cursor, etc.)

Plugin Installation

From Cocos Store (Recommended):
- Visit https://store.cocos.com/app/detail/7941
- Click install and follow prompts in Cocos Creator

Manual Installation:

# Clone the repository
git clone https://github.com/DaxianLee/cocos-mcp-server.git
 
# Install in Cocos Creator extensions folder
# Windows: %USERPROFILE%/.CocosCreator/extensions/
# macOS: ~/.CocosCreator/extensions/
# Copy the plugin folder to the extensions directory

Enable in Cocos Creator:
- Open Cocos Creator
- Go to Extensions → Extension Manager
- Find "Cocos Creator MCP Server" and enable it
- Configure server port (default: 3000) in the MCP panel

Client Configuration

Claude Desktop (claude_desktop_config.json):

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

Claude CLI:

claude mcp add --transport http cocos-creator http://127.0.0.1:3000/mcp

Cursor (.cursor/mcp.json or settings):

{
  "mcpServers": {
    "cocos-creator": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

Core Concepts

Action-Based Tool System

All 50 tools follow a unified "action + parameters" pattern:

{
  "tool": "category_operation",
  "arguments": {
    "action": "specific_action",
    // ... action-specific parameters
  }
}

This design reduces token consumption by ~50% and increases AI call success rates.

Key Tools & Usage

Scene Management

Get Current Scene

// Tool: scene_management
{
  "action": "get_current_scene"
}
// Returns: { uuid: string, name: string, path: string }

Open Scene

{
  "action": "open_scene",
  "sceneUuid": "scene-uuid-here"
}

Create New Scene

{
  "action": "create_scene",
  "name": "MyNewScene",
  "savePath": "db://assets/scenes/"
}

Save Current Scene

{
  "action": "save_scene"
}

Node Operations

Create Node

// Tool: node_lifecycle
{
  "action": "create",
  "name": "PlayerNode",
  "parentUuid": "parent-node-uuid",  // Optional, defaults to scene root
  "nodeType": "2DNode",  // or "3DNode"
  "components": [  // Optional pre-installed components
    {
      "type": "cc.Sprite",
      "properties": {
        "spriteFrame": "texture-uuid"
      }
    }
  ]
}

Query Nodes

// Tool: node_query
{
  "action": "find_by_name",
  "name": "Player",
  "exactMatch": false  // Use pattern matching
}
 
// Or find all nodes
{
  "action": "find_all",
  "includeComponents": true
}

Delete Node

// Tool: node_lifecycle
{
  "action": "delete",
  "uuid": "node-uuid-to-delete"
}

Transform Node

// Tool: node_transform
{
  "action": "set_property",
  "uuid": "node-uuid",
  "property": "position",
  "value": { "x": 100, "y": 200, "z": 0 }
}
 
// Set rotation
{
  "action": "set_property",
  "uuid": "node-uuid",
  "property": "rotation",
  "value": { "x": 0, "y": 0, "z": 45 }  // Euler angles
}
 
// Set scale
{
  "action": "set_property",
  "uuid": "node-uuid",
  "property": "scale",
  "value": { "x": 2, "y": 2, "z": 1 }
}

Move Node in Hierarchy

// Tool: node_hierarchy
{
  "action": "move",
  "uuid": "node-uuid",
  "newParentUuid": "new-parent-uuid",
  "siblingIndex": 0  // Optional position among siblings
}

Component Management

Add Engine Component

// Tool: component_manage
{
  "action": "add",
  "nodeUuid": "node-uuid",
  "componentType": "cc.Sprite",
  "properties": {
    "spriteFrame": "texture-uuid",
    "sizeMode": 0
  }
}
 
// Common component types:
// cc.Sprite, cc.Label, cc.Button, cc.RichText,
// cc.UITransform, cc.Canvas, cc.Widget,
// cc.BoxCollider2D, cc.RigidBody2D, etc.

Attach Custom Script

// Tool: component_script
{
  "action": "add_script",
  "nodeUuid": "node-uuid",
  "scriptName": "PlayerController",  // Script file name without .ts
  "properties": {
    "speed": 100,
    "jumpForce": 500
  }
}

Get Component Information

// Tool: component_query
{
  "action": "get_components",
  "nodeUuid": "node-uuid"
}
// Returns array with type (cid) and properties for each component

Remove Component (IMPORTANT)

// Tool: component_manage
// MUST use component's cid (type field), NOT script name!
// First, get component info:
{
  "action": "get_components",
  "nodeUuid": "node-uuid"
}
// Returns: [{ type: "comp.PlayerController!1234abcd", ... }]
 
// Then remove using exact type (cid):
{
  "action": "remove",
  "nodeUuid": "node-uuid",
  "componentType": "comp.PlayerController!1234abcd"  // Use exact cid
}

Set Component Properties

// Tool: set_component_property
{
  "nodeUuid": "node-uuid",
  "componentType": "cc.Sprite",
  "properties": {
    "color": { "r": 255, "g": 0, "b": 0, "a": 255 }
  }
}
 
// For custom scripts, use full cid from get_components
{
  "nodeUuid": "node-uuid",
  "componentType": "comp.PlayerController!1234abcd",
  "properties": {
    "health": 100,
    "maxSpeed": 200
  }
}

Prefab Operations

List Prefabs

// Tool: prefab_browse
{
  "action": "list",
  "folderPath": "db://assets/prefabs/"  // Optional
}

Create Prefab from Node

// Tool: prefab_lifecycle
{
  "action": "create",
  "nodeUuid": "source-node-uuid",
  "savePath": "db://assets/prefabs/MyPrefab.prefab"
}

Instantiate Prefab

// Tool: prefab_instance
{
  "action": "instantiate",
  "prefabUuid": "prefab-uuid",
  "parentUuid": "parent-node-uuid",  // Optional
  "position": { "x": 0, "y": 0, "z": 0 }  // Optional
}

Apply Instance Changes to Prefab

// Tool: prefab_instance
{
  "action": "apply",
  "nodeUuid": "prefab-instance-uuid"
}

Revert Instance to Original

// Tool: prefab_instance
{
  "action": "revert",
  "nodeUuid": "prefab-instance-uuid"
}

Asset Management

Import Assets

// Tool: asset_manage
{
  "action": "import",
  "paths": [
    "/path/to/texture.png",
    "/path/to/audio.mp3"
  ]
}

Query Assets by Type

// Tool: asset_query
{
  "action": "query_by_type",
  "type": "cc.Texture2D",  // cc.Texture2D, cc.SpriteFrame, cc.Prefab, cc.AudioClip, etc.
  "folder": "db://assets/textures/"  // Optional
}

Get Asset Dependencies

// Tool: asset_analyze
{
  "action": "get_dependencies",
  "uuid": "asset-uuid"
}

Delete Asset

// Tool: asset_operations
{
  "action": "delete",
  "uuid": "asset-uuid"
}

Project Control

Run Project

// Tool: project_manage
{
  "action": "run",
  "preview": true  // false for simulator
}

Build Project

// Tool: project_build_system
{
  "action": "build",
  "platform": "web-mobile",  // web-mobile, android, ios, windows, mac
  "buildPath": "/path/to/build/output"
}

Get Project Info

// Tool: project_manage
{
  "action": "get_info"
}
// Returns project name, version, path, settings

Debugging

Get Console Logs

// Tool: debug_console
{
  "action": "get_logs",
  "filter": "error",  // Optional: log, warn, error
  "limit": 50  // Optional
}

Clear Console

// Tool: debug_console
{
  "action": "clear"
}

Search Log Files

// Tool: debug_logs
{
  "action": "search",
  "pattern": "Error:",
  "maxLines": 100
}

Common Patterns

Creating a Complete Game Object

// 1. Create node
const createNode = {
  tool: "node_lifecycle",
  arguments: {
    action: "create",
    name: "Player",
    nodeType: "2DNode"
  }
};
// Response includes: { uuid: "player-node-uuid" }
 
// 2. Add sprite component
const addSprite = {
  tool: "component_manage",
  arguments: {
    action: "add",
    nodeUuid: "player-node-uuid",
    componentType: "cc.Sprite",
    properties: {
      spriteFrame: "player-texture-uuid"
    }
  }
};
 
// 3. Attach script
const addScript = {
  tool: "component_script",
  arguments: {
    action: "add_script",
    nodeUuid: "player-node-uuid",
    scriptName: "PlayerController",
    properties: {
      speed: 300,
      health: 100
    }
  }
};
 
// 4. Position node
const setPosition = {
  tool: "node_transform",
  arguments: {
    action: "set_property",
    uuid: "player-node-uuid",
    property: "position",
    value: { x: 0, y: 0, z: 0 }
  }
};

Working with Prefabs

// 1. Find a node to convert
const findNode = {
  tool: "node_query",
  arguments: {
    action: "find_by_name",
    name: "Enemy"
  }
};
 
// 2. Create prefab from node
const createPrefab = {
  tool: "prefab_lifecycle",
  arguments: {
    action: "create",
    nodeUuid: "enemy-node-uuid",
    savePath: "db://assets/prefabs/Enemy.prefab"
  }
};
 
// 3. Instantiate multiple times
const spawn1 = {
  tool: "prefab_instance",
  arguments: {
    action: "instantiate",
    prefabUuid: "enemy-prefab-uuid",
    position: { x: 100, y: 0, z: 0 }
  }
};
 
const spawn2 = {
  tool: "prefab_instance",
  arguments: {
    action: "instantiate",
    prefabUuid: "enemy-prefab-uuid",
    position: { x: -100, y: 0, z: 0 }
  }
};

Batch Node Operations

// 1. Find all enemy nodes
const findEnemies = {
  tool: "node_query",
  arguments: {
    action: "find_by_name",
    name: "Enemy",
    exactMatch: false  // Pattern match
  }
};
// Returns: [{ uuid: "enemy1-uuid" }, { uuid: "enemy2-uuid" }, ...]
 
// 2. Delete all enemies
// For each enemy uuid:
const deleteEnemy = {
  tool: "node_lifecycle",
  arguments: {
    action: "delete",
    uuid: "enemy-uuid"
  }
};

Scene Setup Workflow

// 1. Create new scene
const newScene = {
  tool: "scene_management",
  arguments: {
    action: "create_scene",
    name: "Level1",
    savePath: "db://assets/scenes/"
  }
};
 
// 2. Create background node
const background = {
  tool: "node_lifecycle",
  arguments: {
    action: "create",
    name: "Background",
    nodeType: "2DNode",
    components: [{
      type: "cc.Sprite",
      properties: {
        spriteFrame: "bg-texture-uuid"
      }
    }]
  }
};
 
// 3. Create UI canvas
const canvas = {
  tool: "node_lifecycle",
  arguments: {
    action: "create",
    name: "Canvas",
    nodeType: "2DNode",
    components: [{
      type: "cc.Canvas"
    }]
  }
};
 
// 4. Save scene
const saveScene = {
  tool: "scene_management",
  arguments: {
    action: "save_scene"
  }
};

Configuration

Server Settings

Access via MCP panel in Cocos Creator:

Port: Default 3000, customizable
Auto-start: Enable to launch server with editor
Tool Management: Selectively enable/disable specific tools

Tool Configuration

The plugin saves tool configurations in editor preferences. Enable/disable tools through the MCP panel's tool management tab.

Environment Variables

For external integrations, you can configure:

# MCP server endpoint
COCOS_MCP_URL=http://127.0.0.1:3000/mcp
 
# Project path (if automating multiple projects)
COCOS_PROJECT_PATH=/path/to/project

Troubleshooting

Server Won't Start

Issue: MCP server fails to start in Cocos Creator

Solutions:

Check port is not in use: netstat -an | grep 3000
Try different port in MCP panel settings
Restart Cocos Creator
Check extension is enabled in Extension Manager

Tool Calls Failing

Issue: AI can't execute tools or gets errors

Solutions:

Verify server is running (check MCP panel status)
Ensure scene is open (many tools require active scene)
Check UUIDs are valid (use query tools first)
Enable debug logging in console to see detailed errors

Component Removal Fails

Issue: Cannot remove component or script

Solution: Always use the exact cid (type field) from component_query:

// ✅ CORRECT
// First get component info
{ action: "get_components", nodeUuid: "node-uuid" }
// Returns: [{ type: "comp.MyScript!abc123", ... }]
 
// Then remove with exact cid
{
  action: "remove",
  nodeUuid: "node-uuid",
  componentType: "comp.MyScript!abc123"
}
 
// ❌ WRONG - Don't use script name
{
  action: "remove",
  nodeUuid: "node-uuid",
  componentType: "MyScript"  // Will fail!
}

Prefab References Lost

Issue: Prefab loses component or asset references

Solutions:

This was fixed in v1.4.0+
Ensure using latest plugin version
Internal references use {"__id__": x} format
External references set to null (as expected)
Asset references preserve UUID format

Connection Issues

Issue: MCP client can't connect to server

Solutions:

Verify URL in client config matches server port
Check firewall isn't blocking localhost connections
Restart both Cocos Creator and MCP client
Test with: curl http://127.0.0.1:3000/mcp

Performance Degradation

Issue: Editor becomes slow with MCP server

Solutions:

Disable unused tools in tool management
Reduce log levels in debug tools
Limit query result counts
Close unnecessary editor panels

Cross-Platform Path Issues

Issue: Asset paths don't work on different OS

Solution: Always use Cocos db:// protocol for asset paths:

// ✅ CORRECT - Cross-platform
"savePath": "db://assets/prefabs/MyPrefab.prefab"
 
// ❌ WRONG - Platform-specific
"savePath": "/Users/me/project/assets/prefabs/MyPrefab.prefab"

Advanced Usage

Custom Message Broadcasting

// Listen for custom events
const listen = {
  tool: "broadcast_message",
  arguments: {
    action: "listen",
    channel: "game-events"
  }
};
 
// Send custom messages
const broadcast = {
  tool: "broadcast_message",
  arguments: {
    action: "broadcast",
    channel: "game-events",
    message: { event: "player_died", score: 100 }
  }
};

Preferences Management

// Get editor preferences
const getPrefs = {
  tool: "preferences_manage",
  arguments: {
    action: "get",
    key: "editor.grid.snap"
  }
};
 
// Set preferences
const setPrefs = {
  tool: "preferences_manage",
  arguments: {
    action: "set",
    key: "editor.grid.snap",
    value: true
  }
};

System Information

// Get detailed system info
const systemInfo = {
  tool: "debug_system",
  arguments: {
    action: "get_info"
  }
};
// Returns: editor version, OS, memory, performance stats

Best Practices

Always Query Before Modify: Use query tools to get UUIDs before operations
Use Exact CIDs for Components: Never use script names for removal
Save After Major Changes: Call save_scene after structural changes
Validate UUIDs: Check UUIDs exist before referencing
Use db:// Paths: Always use Cocos protocol for cross-platform compatibility
Enable Only Needed Tools: Disable unused tools for better performance
Test Prefabs After Creation: Instantiate and verify before distributing
Handle Errors Gracefully: Check tool responses for success/failure

Resources

GitHub: https://github.com/DaxianLee/cocos-mcp-server
Cocos Store: https://store.cocos.com/app/detail/7941
Video Tutorial: https://www.bilibili.com/video/BV1mB8dzfEw8
Cocos Creator Docs: https://docs.cocos.com/creator/3.8/manual/

Version Compatibility

Plugin Version: 1.5.0+ recommended (1.4.0+ on GitHub)
Cocos Creator: 3.8.6 or higher
MCP Clients: Claude Desktop, Claude CLI, Cursor, VS Code (with MCP extensions)
Node.js: Not required (plugin runs in editor runtime)