Provides comprehensive tools for interacting with the Cocos Creator editor, allowing control over scenes, nodes, components, prefabs, project settings, and assets. Supports 151 tools across 13 categories enabling AI assistants to perform almost all editor operations.
Cocos Creator MCP Server Plugin
A comprehensive MCP (Model Context Protocol) server plugin for Cocos Creator 3.8+, enabling AI assistants to interact with the Cocos Creator editor through standardized protocols. One-click installation and use, eliminating all cumbersome environments and configurations. Claude clients Claude CLI and Cursor have been tested, and other editors are also perfectly supported in theory.
🚀 Now provides 158 tools in 13 categories, achieving 98% editor control! (Prefab instantiation has known child node restoration issues)
Video Demonstrations and Tutorials
Video Demonstration Configuration Tool List
Quick Links
- 📖 Complete Feature Guide (English) - Detailed documentation for all 158 tools(To be completed)
- 📖 完整功能指南 (中文) - 所有158个工具的详细文档(To be completed)
Changelog
v1.3.0 - July 25, 2024
🆕 New Features
- Integrated Tool Management Panel: Added comprehensive tool management functionality directly into the main control panel
- Tool Configuration System: Implemented selective tool enabling/disabling with persistent configurations
- Dynamic Tool Loading: Enhanced tool discovery to dynamically load all 158 available tools from the MCP server
- Real-time Tool State Management: Added real-time updates for tool counts and status when individual tools are toggled
- Configuration Persistence: Automatic saving and loading of tool configurations across editor sessions
🔧 Improvements
- Unified Panel Interface: Merged tool management into the main MCP server panel as a tab, eliminating the need for separate panels
- Enhanced Server Settings: Improved server configuration management with better persistence and loading
- Vue 3 Integration: Upgraded to Vue 3 Composition API for better reactivity and performance
- Better Error Handling: Added comprehensive error handling with rollback mechanisms for failed operations
- Improved UI/UX: Enhanced visual design with proper dividers, distinct block styles, and non-transparent modal backgrounds
🐛 Bug Fixes
- Fixed Tool State Persistence: Resolved issues where tool states would reset upon tab switching or panel re-opening
- Fixed Configuration Loading: Corrected server settings loading issues and message registration problems
- Fixed Checkbox Interactions: Resolved checkbox unchecking issues and improved reactivity
- Fixed Panel Scrolling: Ensured proper scrolling functionality in the tool management panel
- Fixed IPC Communication: Resolved various IPC communication issues between frontend and backend
🏗️ Technical Improvements
- Simplified Architecture: Removed multi-configuration complexity, focusing on single configuration management
- Better Type Safety: Enhanced TypeScript type definitions and interfaces
- Improved Data Synchronization: Better synchronization between frontend UI state and backend tool manager
- Enhanced Debugging: Added comprehensive logging and debugging capabilities
📊 Statistics
- Total Tools: Increased from 151 to 158 tools
- Categories: 13 tool categories with comprehensive coverage
- Editor Control: Achieved 98% editor functionality coverage
v1.2.0 - Previous Version
- Initial release with 151 tools
- Basic MCP server functionality
- Scene, node, component, and prefab operations
- Project control and debugging tools
Claude cli configuration:
Claude client configuration:
Cursor or VS class MCP configuration
Features
🎯 Scene Operations
- Get current scene information and complete scene list
- Open scenes by path and save current scene
- Create new scenes with custom names
- Get complete scene hierarchy with component information
🎮 Node Operations
- Create nodes with 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 project with folder organization
- Load, instantiate, and create prefabs
- Update existing prefabs and revert prefab instances
- Get detailed prefab information including dependencies
- ⚠️ Known Issue: Prefab instantiation may not properly restore child nodes due to Cocos Creator API limitations
🚀 Project Control
- Run project in preview mode (browser/simulator)
- Build project for different platforms (web, mobile, desktop)
- Get project information and settings
- Refresh asset database and import new assets
- Get detailed asset information
🔍 Debug Tools
- Get editor console logs with filtering
- Clear console and execute JavaScript in scene context
- Get detailed node tree for debugging
- Performance statistics and scene validation
- Get editor and environment information
⚙️ Additional Features
- Preferences Management: Get/set editor preferences and global settings
- Server Control: Server information, project details, and editor control
- Message Broadcasting: Listen to and broadcast custom messages
- Asset Management: Create, copy, move, delete, and query assets
- Build System: Project building and preview server control
- Reference Image Management: Add, remove, and manage reference images in scene view
- Scene View Controls: Control gizmo tools, coordinate systems, and view modes
- Advanced Scene Operations: Undo/redo, snapshots, and advanced node manipulation
- 🆕 Tool Management: Selectively enable/disable tools, save configurations, and manage tool states
Installation
1. Copy Plugin Files
Copy the entire cocos-mcp-server
folder to your Cocos Creator project's extensions
directory:
2. Install Dependencies
3. Build the Plugin
4. Enable Plugin
- Restart Cocos Creator or refresh extensions
- The plugin will appear in the Extension menu
- Click
Extension > Cocos MCP Server
to open the control panel
Usage
Starting the Server
- Open the MCP Server panel from
Extension > Cocos MCP Server
- Configure settings:
- Port: HTTP server port (default: 3000)
- Auto Start: Automatically start server when editor opens
- Debug Logging: Enable detailed logging for development
- Max Connections: Maximum concurrent connections allowed
- Click "Start Server" to begin accepting connections
Connecting AI Assistants
The server exposes an HTTP endpoint at http://localhost:3000/mcp
(or your configured port).
AI assistants can connect using the MCP protocol and access all available tools.
Tool Categories
Tools are organized by category with 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.
Example Tool Usage
Create a new sprite node
Add a Sprite component
Instantiate a prefab
⚠️ 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
Configuration
Settings are stored in YourProject/settings/mcp-server.json
:
Tool configurations are stored in YourProject/settings/tool-manager.json
:
Icon Setup
To add an icon for the plugin panel:
- Create a PNG icon file (recommended size: 32x32 or 64x64)
- Place it in the
static/
directory:static/icon.png
- The icon path is already configured in
package.json
Development
Project Structure
Building from Source
Adding New Tools
- Create a new tool class in
source/tools/
- Implement the
ToolExecutor
interface - Add tool to
mcp-server.ts
initialization - Tools are automatically exposed via 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
Troubleshooting
Common Issues
- Server won't start: Check port availability and firewall settings
- Tools not working: Ensure scene is loaded and UUIDs are valid
- Build errors: Run
npm run build
to check for TypeScript errors - Connection issues: Verify HTTP URL and server status
Debug Mode
Enable debug logging in the plugin panel for detailed operation logs.
Using Debug Tools
Requirements
- Cocos Creator 3.8.6 or later
- Node.js (bundled with Cocos Creator)
- TypeScript (installed as 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:
tools/list
method returns available tools - Tool Execution:
tools/call
method executes specific tools
License
This plug-in is for 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.
This server cannot be installed
local-only server
The server can only run on the client's local machine because it depends on local resources.
A comprehensive plugin that enables AI assistants to interact with the Cocos Creator editor through the Model Context Protocol, providing 80 tools across 9 categories for nearly complete editor control.
Related MCP Servers
- AsecurityAlicenseAqualityA Model Context Protocol server that allows AI assistants to interact with Appwrite's API, providing tools to manage databases, users, functions, teams, and other resources within Appwrite projects.Last updated -8446PythonMIT License
- AsecurityAlicenseAqualityProvides an interface between AI assistants and Tripo AI via Model Context Protocol, enabling generation of 3D assets from natural language and importing them to Blender.Last updated -15166PythonMIT License
- -securityAlicense-qualityA Model Context Protocol server that allows AI assistants to invoke and interact with Integrator automation workflows through an API connection.Last updated -4TypeScriptMIT License
WordPress MCPofficial
AsecurityFlicenseAqualityA WordPress plugin that implements the Model Context Protocol to enable AI models and applications to interact with WordPress sites in a structured and secure way.Last updated -513350