cocos-creator-mcp-server

# Cocos Creator MCP Server Skill > Skill by [ara.so](https://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 1. **From Cocos Store** (Recommended): - Visit https://store.cocos.com/app/detail/7941 - Click install and follow prompts in Cocos Creator 2. **Manual Installation**: ```bash # 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 ``` 3. **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`): ```json { "mcpServers": { "cocos-creator": { "type": "http", "url": "http://127.0.0.1:3000/mcp" } } } ``` **Claude CLI**: ```bash claude mcp add --transport http cocos-creator http://127.0.0.1:3000/mcp ``` **Cursor** (`.cursor/mcp.json` or settings): ```json { "mcpServers": { "cocos-creator": { "url": "http://localhost:3000/mcp" } } } ``` ## Core Concepts ### Action-Based Tool System All 50 tools follow a unified "action + parameters" pattern: ```typescript { "tool": "category_operation", "arguments": { "action": "specific_action", // ... action-specific parameters } } ``` This design reduces token consumption by ~50% and increases AI call success rates. ### Tool Categories - **scene_*** - Scene management and hierarchy - **node_*** - Node lifecycle, transforms, and hierarchy - **component_*** - Component management and scripting - **prefab_*** - Prefab browsing, creation, and instantiation - **asset_*** - Asset management and analysis - **project_*** - Project control and build system - **debug_*** - Console, logs, and system debugging - **preferences_*** - Editor preferences - **server_*** - Server information - **broadcast_*** - Message broadcasting ## Key Tools & Usage ### Scene Management #### Get Current Scene ```typescript // Tool: scene_management { "action": "get_current_scene" } // Returns: { uuid: string, name: string, path: string } ``` #### Open Scene ```typescript { "action": "open_scene", "sceneUuid": "scene-uuid-here" } ``` #### Create New Scene ```typescript { "action": "create_scene", "name": "MyNewScene", "savePath": "db://assets/scenes/" } ``` #### Save Current Scene ```typescript { "action": "save_scene" } ``` ### Node Operations #### Create Node ```typescript // 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 ```typescript // 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 ```typescript // Tool: node_lifecycle { "action": "delete", "uuid": "node-uuid-to-delete" } ``` #### Transform Node ```typescript // 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 ```typescript // Tool: node_hierarchy { "action": "move", "uuid": "node-uuid", "newParentUuid": "new-parent-uuid", "siblingIndex": 0 // Optional position among siblings } ``` ### Component Management #### Add Engine Component ```typescript // 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 ```typescript // Tool: component_script { "action": "add_script", "nodeUuid": "node-uuid", "scriptName": "PlayerController", // Script file name without .ts "properties": { "speed": 100, "jumpForce": 500 } } ``` #### Get Component Information ```typescript // Tool: component_query { "action": "get_components", "nodeUuid": "node-uuid" } // Returns array with type (cid) and properties for each component ``` #### Remove Component (IMPORTANT) ```typescript // 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 ```typescript // 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 ```typescript // Tool: prefab_browse { "action": "list", "folderPath": "db://assets/prefabs/" // Optional } ``` #### Create Prefab from Node ```typescript // Tool: prefab_lifecycle { "action": "create", "nodeUuid": "source-node-uuid", "savePath": "db://assets/prefabs/MyPrefab.prefab" } ``` #### Instantiate Prefab ```typescript // 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 ```typescript // Tool: prefab_instance { "action": "apply", "nodeUuid": "prefab-instance-uuid" } ``` #### Revert Instance to Original ```typescript // Tool: prefab_instance { "action": "revert", "nodeUuid": "prefab-instance-uuid" } ``` ### Asset Management #### Import Assets ```typescript // Tool: asset_manage { "action": "import", "paths": [ "/path/to/texture.png", "/path/to/audio.mp3" ] } ``` #### Query Assets by Type ```typescript // 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 ```typescript // Tool: asset_analyze { "action": "get_dependencies", "uuid": "asset-uuid" } ``` #### Delete Asset ```typescript // Tool: asset_operations { "action": "delete", "uuid": "asset-uuid" } ``` ### Project Control #### Run Project ```typescript // Tool: project_manage { "action": "run", "preview": true // false for simulator } ``` #### Build Project ```typescript // Tool: project_build_system { "action": "build", "platform": "web-mobile", // web-mobile, android, ios, windows, mac "buildPath": "/path/to/build/output"