Cocos Creator MCP server

This plugin enables seamless AI interaction with Cocos Creator through a Model Context Protocol (MCP) server, allowing AI assistants to directly control the editor with 50 powerful integrated tools covering 99% of editor functionality. The server works with Claude, Cursor, and other AI tools that support the MCP protocol.

Installation

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 the plugin here
│       ├── source/
│       ├── dist/
│       ├── package.json
│       └── ...
├── settings/
└── ...

Install Dependencies

cd extensions/cocos-mcp-server
npm install

Build Plugin

npm run build

Enable Plugin

1. Restart Cocos Creator or refresh extensions
2. Open the plugin from the Extensions menu
3. Click Extensions > Cocos MCP Server to open the control panel

Usage

Starting the Server

1. Open the MCP server panel from Extensions > Cocos MCP Server

2. Configure settings:

   • Port: HTTP server port (default: 3000)
   • Auto Start: Automatically start server when editor launches
   • Debug Logs: Enable detailed logs for debugging
   • Max Connections: Maximum allowed concurrent connections

3. Click "Start Server" to begin accepting connections

Connecting AI Assistants

Claude CLI Configuration

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

Claude Desktop Client Configuration

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

Cursor or VS Code Configuration

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

Core Features

Scene Operations (scene_*)

• scene_management: Get current scene, open/save/create/close scenes, query scene list
• scene_hierarchy: Get complete scene structure with component information
• scene_execution_control: Execute component methods, scene scripts, prefab synchronization

Node Operations (node_*)

• node_query: Find nodes by name/pattern, get node info, detect 2D/3D types
• node_lifecycle: Create/delete nodes with pre-installed components
• node_transform: Modify node name, position, rotation, scale, visibility
• node_hierarchy: Move, copy, paste nodes with hierarchy structure support

Component Operations (component_*)

• component_manage: Add/remove engine components (cc.Sprite, cc.Button, etc.)
• component_script: Mount/remove custom script components
• component_query: Get component lists, detailed info, available component types
• set_component_property: Set single or multiple component property values

Prefab Operations (prefab_*)

• prefab_browse: List prefabs, view info, validate files
• prefab_lifecycle: Create prefabs from nodes, delete prefabs
• prefab_instance: Instantiate to scene, unlink, apply changes, revert to original
• prefab_edit: Enter/exit edit mode, save prefabs, test changes

Example Tool Usage

{
  "tool": "node_lifecycle",
  "arguments": {
    "action": "create",
    "name": "MyNode",
    "parentUuid": "parent-uuid",
    "nodeType": "2DNode"
  }
}

Additional Features

Project Control (project_*)

• project_manage: Run project, build project, get project information and settings
• project_build_system: Control build panel, check build status, preview server management

Debug Tools (debug_*)

• debug_console: Get/clear console logs with filtering support
• debug_logs: Read/search/analyze project log files with pattern matching
• debug_system: Get editor info, performance statistics, environment information

Asset Management (asset_*)

• asset_manage: Batch import/delete assets, save metadata, generate URLs
• asset_analyze: Get dependency relationships, export asset inventories

Preferences (preferences_*)

• preferences_manage: Get/set editor preferences
• preferences_global: Manage global configuration and system settings

Server & Broadcasting (server_* / broadcast_*)

• server_info: Get server status, project details, environment information
• broadcast_message: Listen for and broadcast custom messages

Troubleshooting

Common Issues

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

Debug Mode

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

Using Debug Tools

{
  "tool": "debug_console",
  "arguments": {
    "action": "getLogs",
    "limit": 50,
    "filter": "error"
  }
}

{
  "tool": "debug_logs",
  "arguments": {
    "action": "analyze",
    "pattern": "error"
  }
}

System Requirements

• Cocos Creator 3.8.6 or higher
• Node.js (included with Cocos Creator)

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "cocos-creator" '{"url":"http://localhost:3000/mcp"}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect