Cocos MCP Server

🚀 Cocos Creator MCP Server Plugin

This is a comprehensive MCP (Model Context Protocol) server plugin for Cocos Creator 3.8+. It enables AI assistants to interact with the Cocos Creator editor through standardized protocols. With one - click installation and use, it eliminates all cumbersome environments and configurations. The Claude clients Claude CLI and Cursor have been tested, and other editors are also perfectly supported in theory.

🚀 Quick Start

Configuration for Different Clients

• Claude cli configuration:

claude mcp add --transport http cocos-creator http://127.0.0.1:3000/mcp (use the port number you configured yourself)

• Claude client configuration:

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

• Cursor or VS class MCP configuration:

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

✨ Features

🎯 Scene Operations

• Retrieve current scene information and the complete scene list.
• Open scenes by path and save the current scene.
• Create new scenes with custom names.
• Obtain the complete scene hierarchy with component information.

🎮 Node Operations

• Create nodes of different types (Node, 2DNode, 3DNode).
• Get node information by UUID and find nodes by name pattern.
• Set node properties (position, rotation, scale, active).
• Delete, move, and duplicate nodes with full hierarchy support.

🔧 Component Operations

• Add/remove components from nodes.
• Get all components of a node with properties.
• Set component properties dynamically.
• Attach script components from asset paths.
• List available component types by category.

📦 Prefab Operations

• List all prefabs in the project with folder organization.
• Load, instantiate, and create prefabs.
• Update existing prefabs and revert prefab instances.
• Get detailed prefab information including dependencies.

⚠️ Important Note

Prefab instantiation may not properly restore child nodes due to Cocos Creator API limitations.

🚀 Project Control

• Run the project in preview mode (browser/simulator).
• Build the project for different platforms (web, mobile, desktop).
• Get project information and settings.
• Refresh the asset database and import new assets.
• Get detailed asset information.

🔍 Debug Tools

• Get editor console logs with filtering.
• Clear the console and execute JavaScript in the scene context.
• Get the detailed node tree for debugging.
• Obtain performance statistics and perform scene validation.
• Get editor and environment information.

⚙️ Additional Features

• Preferences Management: Get/set editor preferences and global settings.
• Server Control: Retrieve server information, project details, and control the editor.
• Message Broadcasting: Listen to and broadcast custom messages.
• Asset Management: Create, copy, move, delete, and query assets.
• Build System: Control project building and the preview server.
• Reference Image Management: Add, remove, and manage reference images in the scene view.
• Scene View Controls: Control gizmo tools, coordinate systems, and view modes.
• Advanced Scene Operations: Undo/redo, take snapshots, and perform advanced node manipulation.

📦 Installation

1. Copy Plugin Files

Copy the entire cocos-mcp-server folder to your Cocos Creator project's extensions directory:

YourProject/
├── assets/
├── extensions/
│   └── cocos-mcp-server/          <- Place plugin here
│       ├── source/
│       ├── dist/
│       ├── package.json
│       └── ...
├── settings/
└── ...

2. Install Dependencies

cd extensions/cocos-mcp-server
npm install

3. Build the Plugin

npm run build

4. Enable Plugin

1. Restart Cocos Creator or refresh extensions.
2. The plugin will appear in the Extension menu.
3. Click Extension > Cocos MCP Server to open the control panel.

💻 Usage Examples

Basic Usage

Create a new sprite node

{
    "tool": "node_create_node",
    "arguments": {
        "name": "MySprite",
        "nodeType": "2DNode",
        "parentUuid": "parent-node-uuid"
    }
}

Add a Sprite component

{
    "tool": "component_add_component", 
    "arguments": {
        "nodeUuid": "node-uuid",
        "componentType": "cc.Sprite"
    }
}

Instantiate a prefab

{
    "tool": "prefab_instantiate_prefab",
    "arguments": {
        "prefabPath": "db://assets/prefabs/Enemy.prefab",
        "position": { "x": 100, "y": 200, "z": 0 }
    }
}

⚠️ Important Note

Complex prefabs with child nodes may not instantiate correctly due to Cocos Creator API limitations. Child nodes may be missing in the instantiated prefab.

Run project in browser

{
    "tool": "project_run_project",
    "arguments": {
        "platform": "browser"
    }
}

Tool Categories

Tools are organized by category with the naming convention: category_toolname

• scene_*: Scene-related operations (8 tools)
• node_*: Node manipulation (9 tools)
• component_*: Component management (7 tools)
• prefab_*: Prefab operations (11 tools)
• project_*: Project control (22 tools)
• debug_*: Debugging utilities (10 tools)
• preferences_*: Editor preferences (7 tools)
• server_*: Server information (6 tools)
• broadcast_*: Message broadcasting (5 tools)
• assetAdvanced_*: Advanced asset operations (10 tools)
• referenceImage_*: Reference image management (12 tools)
• sceneAdvanced_*: Advanced scene operations (23 tools)
• sceneView_*: Scene view controls (14 tools)

📖 View Complete Tool Documentation for detailed usage examples and parameters.

📚 Documentation

Configuration

Settings are stored in YourProject/settings/mcp-server.json:

{
    "port": 3000,
    "autoStart": false,
    "enableDebugLog": true,
    "allowedOrigins": ["*"],
    "maxConnections": 10
}

Icon Setup

To add an icon for the plugin panel:

1. Create a PNG icon file (recommended size: 32x32 or 64x64).
2. Place it in the static/ directory: static/icon.png.
3. The icon path is already configured in package.json.

Development

Project Structure

cocos-mcp-server/
├── source/                    # TypeScript source files
│   ├── main.ts               # Plugin entry point
│   ├── mcp-server.ts         # MCP server implementation
│   ├── settings.ts           # Settings management
│   ├── types/                # TypeScript type definitions
│   ├── tools/                # Tool implementations
│   │   ├── scene-tools.ts
│   │   ├── node-tools.ts
│   │   ├── component-tools.ts
│   │   ├── prefab-tools.ts
│   │   ├── project-tools.ts
│   │   ├── debug-tools.ts
│   │   ├── preferences-tools.ts
│   │   ├── server-tools.ts
│   │   ├── broadcast-tools.ts
│   │   ├── scene-advanced-tools.ts
│   │   ├── scene-view-tools.ts
│   │   ├── reference-image-tools.ts
│   │   └── asset-advanced-tools.ts
│   ├── panels/               # UI panel implementation
│   └── test/                 # Test files
├── dist/                     # Compiled JavaScript output
├── static/                   # Static assets (icons, etc.)
├── i18n/                     # Internationalization files
├── package.json              # Plugin configuration
└── tsconfig.json             # TypeScript configuration

Building from Source

# Install dependencies
npm install

# Build for development with watch mode
npm run watch

# Build for production
npm run build

Adding New Tools

1. Create a new tool class in source/tools/.
2. Implement the ToolExecutor interface.
3. Add the tool to mcp-server.ts initialization.
4. Tools are automatically exposed via the MCP protocol.

TypeScript Support

The plugin is fully written in TypeScript with:

• Strict type checking enabled.
• Comprehensive type definitions for all APIs.
• IntelliSense support for development.
• Automatic compilation to JavaScript.

Running Tests

# Run comprehensive test suite
node comprehensive-test.js

# Run feature-specific tests
./test-all-features.sh

# Run Node.js test script
node test-mcp-server.js

Troubleshooting

Common Issues

• Server won't start: Check port availability and firewall settings.
• Tools not working: Ensure the scene is loaded and UUIDs are valid.
• Build errors: Run npm run build to check for TypeScript errors.
• Connection issues: Verify the HTTP URL and server status.

Debug Mode

Enable debug logging in the plugin panel for detailed operation logs.

Using Debug Tools

{
    "tool": "debug_get_console_logs",
    "arguments": {"limit": 50, "filter": "error"}
}

{
    "tool": "debug_validate_scene",
    "arguments": {"checkMissingAssets": true}
}

🔧 Technical Details

Requirements

• Cocos Creator 3.8.6 or later.
• Node.js (bundled with Cocos Creator).
• TypeScript (installed as a dev dependency).

Architecture Notes

This plugin uses a simplified MCP protocol implementation that is compatible with Cocos Creator's CommonJS environment. The HTTP server provides a JSON - RPC interface for AI assistants to interact with the editor.

Protocol Support

• HTTP Connection: http://localhost:3000/mcp (configurable port).
• JSON-RPC 2.0: Standard request/response format.
• Tool Discovery: The tools/list method returns available tools.
• Tool Execution: The tools/call method executes specific tools.

📄 License

This plug - in is for the Cocos Creator project, and the source code is packaged together, which can be used for learning and communication. It is not encrypted. It can support your own secondary development and optimization. Any code of this project or its derivative code cannot be used for any commercial purpose or resale. If you need commercial use, please contact me.