Content
# Cocos MCP for Cocos Creator 2.x
MCP Server extension for Cocos Creator 2.x, aiming to enable AI assistants to operate Cocos Creator 2.4.x projects through the MCP protocol for page construction, scene modification, node layout, component configuration, script generation, and script mounting.
The current version focuses on supporting Cocos Creator 2.x, with compatibility design for 2.4.x usage.
## Features
- MCP HTTP Service: Launches a local MCP Server within the Cocos Creator extension, with a default address of `http://127.0.0.1:3100/mcp`.
- Editor Panel: Provides a Cocos MCP 2.x control panel within Creator, allowing configuration of port, startup, and service stoppage.
- Scene Operations: Reads the current scene, opens/saves scenes, retrieves layer structure, and executes scene process auxiliary logic.
- Node Operations: Queries, creates, deletes, copies, moves nodes, and modifies position, size, rotation, scale, activation state, name, etc.
- Component Operations: Adds/removes components, queries components, sets component properties, mounts script components, and supports binding resource fields through dedicated interfaces.
- Asset Operations: Queries, creates, copies, moves, deletes, imports assets, reads meta/uuid, and refreshes AssetDB after file changes.
- Script Workflow: Reads, creates, updates, appends, deletes script files, refreshes script assets, and supports creating scripts and mounting them to nodes.
- Prefab Basic Operations: Browses, creates, copies, deletes prefabs, and instantiates prefabs into the current scene.
- Build/Preview Assistance: Reads Creator 2.x build configuration, opens the Builder panel, opens the Game Preview panel, and detects build/preview capability boundaries.
- Scene Saving: Saves scenes through editor memory scene serialization and `assetdb.createOrSave`, without relying on unstable `Editor.scene.save`.
- Scene Resource Binding: Binds resources to nodes and script fields through formal tools, and directly saves the current scene.
- Batch Plan Execution: Executes multi-step scene plans generated by YAML/Figma analysis through `workflow_plan`, `workflow_scene_apply`, and `workflow_scene_bind`.
- Tool Configuration Management: Supports tool switch configuration and automatically adapts to old asset tool configurations.
## Current Positioning
This project is not an official Cocos Creator automation interface, nor is it a complete, headless build system that replaces the editor UI. It is a Creator 2.x extension layer for AI agents, responsible for converting MCP tool calls into editor, scene, and file operations that Creator 2.x can execute.
Suitable for:
- Creating or adjusting Cocos UI pages based on design drafts.
- Batch-modifying node layouts, hierarchies, and component properties.
- Generating TypeScript/JavaScript scripts and mounting them to specified nodes.
- Querying and importing resources, and refreshing the Creator resource database.
- Assisting AI in maintaining Cocos Creator 2.x project structure.
Not suitable for direct commitment:
- Complete headless construction.
- Complete headless preview server lifecycle control.
Due to unstable and unpublished internal APIs of Creator 2.x's Builder, Preview, and Prefab, this project adopts a strategy of "controlling what can be controlled, and clearly returning capability boundaries for what cannot be stably controlled."
## Installation Instructions
### Environment Requirements
- Cocos Creator 2.x, recommended 2.4.x.
- Node.js and npm for compiling TypeScript.
- A Cocos Creator 2.x project.
### Building the Extension
Execute in the repository directory:
```bash
cd <cocos-mcp-repo>
npm install
npm run build
```
After building, the `dist/` directory will be generated. The actual loading entry for Creator is:
- `main.js` -> `dist/main.js`
- `scene.js` -> `dist/scene.js`
### Installing to a Cocos Creator Project
Recommended to symlink this repository to the target project's `packages/cocos-mcp`:
```bash
cd <your-cocos-project>
mkdir -p packages
ln -s <cocos-mcp-repo> packages/cocos-mcp
```
Alternatively, directly copy the entire directory:
```bash
mkdir -p <your-cocos-project>/packages
cp -R <cocos-mcp-repo> <your-cocos-project>/packages/cocos-mcp
```
Where:
- `<cocos-mcp-repo>` represents the directory where this repository is located, e.g., `/path/to/cocos-mcp`.
- `<your-cocos-project>` represents the root directory of your Cocos Creator 2.x project, which contains `assets/`, `settings/`, and `project.json`.
After installation, restart Cocos Creator or reload the extension in the extension/package management interface.
### Opening the Control Panel
Open in the Cocos Creator menu:
```text
Panel -> Cocos MCP 2.x
```
If the panel is not visible in the menu:
- Confirm the extension directory is located under `packages/cocos-mcp` in the project.
- Confirm `npm run build` has been executed, and `dist/main.js` and `dist/scene.js` exist.
- Reload `cocos-mcp` in the extension/package management panel.
- Check the Creator console for extension loading errors.
## Usage
### Starting the MCP Service
1. Open the Cocos Creator project.
2. Open `Panel -> Cocos MCP 2.x`.
3. Keep the default port `3100` or input a custom port.
4. Click `Start`.
5. Access the health check address in the browser:
```text
http://127.0.0.1:3100/health
```
Normal response example:
```json
{
"status": "ok",
"running": true,
"port": 3100,
"clients": 1,
"tools": 30
}
```
### Common Endpoints
- Health check: `http://127.0.0.1:3100/health`
- MCP endpoint: `http://127.0.0.1:3100/mcp`
- Tool list: `http://127.0.0.1:3100/api/tools`
### Verifying the MCP Tool List
```bash
curl http://127.0.0.1:3100/api/tools
```
If the service is normal, you should see `scene_management`, `component_resource`, `script_workflow`, `workflow_scene_apply`, `workflow_scene_bind`, etc.
## Recommended Workflow
### Resource Binding and Scene Saving
From the current version, it is not recommended to directly modify `.fire` files by AI or manually. The recommended order is:
1. Query the current scene, nodes, components, and resource UUIDs through MCP.
2. Complete resource binding in the editor's memory scene using `workflow_scene_bind` or `scene_management`'s `bind_resources` action.
3. Let MCP save the current scene through the editor API.
Recommended reasons:
- Avoid "disk `.fire`" and "editor memory scene" state bifurcation.
- Avoid incorrect IPC or external patch writing the scene to a bad state.
- Keep resource binding, node adjustment, and saving in the same Creator runtime link.
### When to Use Which Tool
- Ordinary value property modification: Prioritize `component_property`
- Suitable for `boolean`, `number`, `string`, ordinary objects, node references, component references, etc.
- Resource field binding: Prioritize `component_resource` or `workflow_scene_bind`
- Suitable for `cc.SpriteFrame`, custom script `@property(cc.SpriteFrame)`, etc.
- Page/scene batch modification: Prioritize `workflow_scene_apply`
- Resource binding + automatic saving: Prioritize `workflow_scene_bind`
## Tool System
The current MCP service exposes 30 tools. Tool names adopt the `category_operation` style, and each tool is distinguished by an `action` parameter internally.
### Scene Tools
| Tool | Description |
| --- | --- |
| `scene_management` | Scene management, including current scene, scene list, opening/reloading/saving/creating scenes, and resource binding. |
| `scene_hierarchy` | Reads the current scene node hierarchy. |
| `scene_execution_control` | Low-level scene process auxiliary tool for calling scene-script capabilities. |
### Node Tools
| Tool | Description |
| --- | --- |
| `node_query` | Queries nodes and reads node details. |
| `node_lifecycle` | Creates, deletes, moves, copies nodes. |
| `node_transform` | Modifies node properties and transform, including position, size, rotation, scale, etc. |
### Component Tools
| Tool | Description |
| --- | --- |
| `component_manage` | Adds or removes components. |
| `component_query` | Queries node components and available built-in components. |
| `component_property` | Sets component properties, supporting ordinary values, node references, component references, and some typed asset references. |
| `component_resource` | Binds strong-type resource fields through dedicated interfaces, e.g., `SpriteFrame`. |
| `component_script` | Mounts script components to nodes by script class name. |
### Prefab Tools
| Tool | Description |
| --- | --- |
| `prefab_browse` | Lists and inspects prefab assets. |
| `prefab_lifecycle` | Creates, copies, deletes prefab assets. |
| `prefab_instance` | Instantiates prefabs into the current scene. |
### Project and Asset Tools
| Tool | Description |
| --- | --- |
| `project_manage` | Gets project information, project settings, refreshes assets, opens preview panels. |
| `project_build_system` | Build/preview assistance, including reading build configuration, opening Builder, opening Preview, detecting capability boundaries. |
| `project_asset_query` | Queries assets by path, type, name. |
| `project_asset_operations` | Creates, copies, moves, deletes, saves, imports, refreshes assets. |
| `project_asset_analyze` | Queries asset uuid/meta information. |
### Script Tools
| Tool | Description |
| --- | --- |
| `script_file` | Reads, creates, updates, appends, deletes script files, and refreshes script assets. |
| `script_workflow` | Creates scripts and mounts them, mounts existing scripts, and refreshes and mounts scripts. |
### Workflow Tools
| Tool | Description |
| --- | --- |
| `workflow_plan` | Executes or dry-runs a set of MCP tool call steps, suitable for undertaking page generation plans converted from Figma/YAML. |
| `workflow_scene_apply` | Executes a set of scene steps, supporting before and after scene reloading, script refreshing, and scene saving. |
| `workflow_scene_bind` | Executes a set of formal scene resource binding steps and can directly save the current scene. |
### Debug and Server Tools
| Tool | Description |
| --- | --- |
| `debug_console` | Debugging and diagnosis assistance. |
| `debug_logs` | Reads project or editor logs. |
| `preferences_manage` | Manages extension's own preference configuration. |
| `broadcast_message` | Lightweight internal broadcast logging. |
| `validation_helpers` | Small parameter validation assistance for AI clients. |
| `server_info` | Queries MCP service status and local network information. |
## Connecting AI Assistant Configuration
### Codex
Add the MCP configuration of this service to Codex. The specific configuration file location depends on your Codex installation method, with the core configuration as follows:
```toml
[mcp_servers.cocos-mcp]
url = "http://127.0.0.1:3100/mcp"
```
Restart Codex after configuration and confirm that the MCP list shows `cocos-mcp` with a tool count not equal to 0.
If Codex displays `Tools: (none)`:
- Confirm the service is started in the Creator panel.
- Confirm `http://127.0.0.1:3100/health` returns `running: true`.
- Confirm `http://127.0.0.1:3100/api/tools` shows the tool list.
- Restart Codex to let the MCP client re-execute initialize and tools/list.
- Confirm the configuration URL is `/mcp`, not `/health` or `/api/tools`.
### Claude Desktop / Other MCP Clients
If the client supports HTTP/Streamable HTTP MCP, configure the URL:
```text
http://127.0.0.1:3100/mcp
```
If the client only supports stdio MCP, it cannot directly connect to this extension, requiring an additional HTTP-to-stdio MCP proxy.
### Cursor / Continue / Other Editor Assistants
Prioritize the HTTP MCP Server configuration method, filling in the URL:
```text
http://127.0.0.1:3100/mcp
```
If the client requires a transport type, choose HTTP, Streamable HTTP, or remote MCP. Do not choose stdio unless you have an additional proxy configured.
## Troubleshooting
### Do Not Let Models Manually Modify `.fire`
It is not recommended to directly patch scene `.fire` files manually, as:
- The scene Creator opens is in-memory.
- Directly modifying disk files can easily be overwritten by subsequent saves.
- Resource field serialization formats can be easily written incorrectly.
- Different Creator 2.x minor versions have inconsistent scene write-back details.
Recommended practices:
- Node/component modifications: Complete through MCP tools.
- Resource binding: Complete through `component_resource` or `workflow_scene_bind`.
- Saving: Complete through `scene_management.save`.
### Panel Always Loading
Possible reasons:
- The extension main process did not load correctly.
- `dist/main.js` does not exist.
- `main.js` entry cannot require `dist/main.js`.
- Creator cached an old extension.
Handling:
```bash
cd <cocos-mcp-repo>
npm run build
```
Then reload the extension in Creator's extension/package management, or restart Creator if necessary.
### Console Prompts `Failed to uncache module dist/main.js: Cannot find it`
Indicates that the build has not been performed or the build product is missing.
Handling:
```bash
cd <cocos-mcp-repo>
npm install
npm run build
```
### Console Prompts `[methods] in package [cocos-mcp] is not a function`
Usually, it is due to Creator 2.x extension export format incompatibility or loading old code.
Handling:
- Confirm `src/main.ts` exports `methods() {}`.
- Execute `npm run build`.
- Reload the extension or restart Creator.
### `component_property` or `component_resource` Fails on Resource Fields
If it's `cc.SpriteFrame`, material, Prefab, etc. resource fields, do not try to write object or directly guess `.fire` serialization structure.
Recommended order:
1. Use `workflow_scene_bind` to bind resources and save.
2. Or use `scene_management`'s `bind_resources` action.
3. If necessary, fall back to `scene_execution_control.execute_debug_script` for one-time troubleshooting.
Explanation:
- `component_property` is most stable for ordinary values.
- Resource field binding prioritizes dedicated scene resource tools.
### `scene_management.save` Fails
The current version of `scene_management.save` prioritizes using editor memory scene serialization and then saving through `assetdb.createOrSave`.
If it still fails, usually due to:
- The current scene URL cannot be resolved.
- `Editor.assetdb.createOrSave` is not available in the current editor context.
- The scene has been destroyed by a third-party extension or an abnormal state.
Suggested handling:
- Call `scene_management.get_current` to confirm the current scene.
- Call `scene_management.reload_current` to reload the scene.
- Then re-execute `workflow_scene_bind` or `workflow_scene_apply`.
### Build/Preview Cannot Be Completely Controlled by AI
This is a limitation of Creator 2.x extension APIs. The current stable capabilities are:
- Open the Builder panel.
- Read `settings/builder.json`.
- Open the Game Preview panel.
- Detect build/preview capability boundaries.
Complete build parameter confirmation and final build suggestions are still recommended through the Creator Builder panel.
## Development Instructions
Common commands:
```bash
npm run build
npm run watch
```
Main source code:
- `src/main.ts`: Creator extension main process entry.
- `src/scene.ts`: Creator scene-script entry, responsible for node and component operations within the scene.
- `src/mcp-server.ts`: MCP HTTP service implementation.
- `src/tool-catalog.ts`: Tool catalog and default switches.
- `src/tools/*`: Various MCP tool implementations.
After modifying the source code, rebuild:
```bash
npm run build
```
Then reload the extension in Creator.
## Security Instructions
The MCP service listens to:
```text
127.0.0.1
```
By default, only the local machine can access it. Do not change it to `0.0.0.0` to expose it to the LAN or public network, as this service has the ability to modify project files, scripts, and scenes.
## License
`MIT`
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available