Cocos MCP Community

English | 简体中文

A community-built Model Context Protocol (MCP) extension for Cocos Creator 3.8+. Connect a compatible AI client to inspect and operate the project currently open in Cocos Creator.

The extension runs locally, listens on 127.0.0.1, and requires explicit confirmation for persistent or structural changes.

Current version: 0.2.3. The automated suite passes, and the main read and isolated-write workflows have been verified with Cocos Creator 3.8.8.

Features

The server exposes 23 intent-oriented MCP tools. Each tool groups related actions so clients receive a focused tool list while retaining broad editor coverage.

Tool	Capabilities
project	Read project information and asset summaries; query or update project configuration
scene	Inspect the active scene and hierarchy; open, save, or save as a scene
node	Find, inspect, create, update, duplicate, copy, cut, paste, reset, reparent, or delete nodes
component	List, add, remove, inspect, edit, or reset components; edit arrays and Button events; apply text styles
asset	Check AssetDB, list and inspect assets, read safe text assets, import, create, save, copy, move, refresh, reimport, or delete
prefab	List and inspect Prefabs, find usage, instantiate linked or unlinked copies, copy or delete assets, and restore instances
snapshot	Capture and restore hierarchy snapshots; begin, commit, or abort scoped structure transactions
builder	Create validated node trees or a complete Canvas/Panel/Title/Button UI screen atomically
validation	Check hierarchy and UI issues; validate references; analyze dependencies, cycles, missing items, and orphan candidates
capture	Capture structured layout data, a Camera-rendered PNG, or a cropped local Preview-canvas PNG
animation	Create, save, batch-generate, inspect, and incrementally edit AnimationClips; attach and control clips
viewport	Read design resolution and editor view state; focus or align nodes; configure 2D, grid, gizmo, and icon options
editor	Read editor context, selection, dirty state, readiness, Creator Console entries, project logs, and Preview errors
preview	Inspect Preview networking, start supported Preview targets, reload Preview, stop Game View, and click local Preview buttons
ui	Ensure a Canvas and create templates, Layout containers, dialogs, lists, navigation bars, or settings screens
spine	Assign Spine data and list, play, queue, or clear animations on sp.Skeleton components
font	List project fonts and apply a project font or system font to cc.Label
reference_image	List SpriteFrames and place an in-scene reference image from a project asset
environment	Inspect engine and native paths, devices, editor networking, programming settings, and plugins
knowledge	Search built-in Cocos workflow guidance by topic
server	Read local service status and recent operation metadata
preferences	Inspect, disable, enable, or reset the project-local tool selection
client_config	Generate client configuration for Claude Desktop, Cursor, VS Code, or Windsurf

Additional workflow features include session-aware Streamable HTTP, tool-list change notifications, schema-validated inputs, confirmation gates, rollback-aware batch operations, and project-local tool presets.

Requirements

• Cocos Creator 3.8 or later
• Node.js 18 or later
• npm
• An MCP client with Streamable HTTP support

Installation and usage

1. Install the extension

Clone the repository into the Cocos project's extensions directory, install dependencies, and build:

cd /path/to/YourCocosProject/extensions
git clone <repository-url> cocos-mcp-community
cd cocos-mcp-community
npm ci
npm run build

Open the project in Cocos Creator. If the editor was already open, reload extensions or restart the editor.

2. Start the MCP server

Open Extension → Cocos MCP Community and select Start server. The default endpoint is:

http://127.0.0.1:3100/mcp

The panel displays the active endpoint and server status. You can also change the project-local port or enable automatic startup.

3. Connect an MCP client

Add a Streamable HTTP server to the MCP settings of your client. The generic server entry is:

{
  "type": "http",
  "url": "http://127.0.0.1:3100/mcp"
}

The surrounding configuration differs between clients. After the first connection, the client_config tool can generate complete entries for Claude Desktop, Cursor, VS Code, and Windsurf.

Restart or reconnect the MCP client after changing its configuration. If the server port is changed in the Cocos panel, update the client URL as well.

4. Verify the connection

Keep the target project and scene open in Cocos Creator, then ask the AI client for a read-only action such as:

Summarize the current Cocos scene hierarchy.

List the assets under db://assets and report any missing references.

Check the current editor and Preview errors without changing the project.

If the client can return project or scene information, the connection is ready.

5. Use editing workflows

You can describe editor tasks in natural language. For example:

Create a Canvas with a centered panel, a title, and a button in the current scene.

Set the selected Label font size to 32 and change its text to "Play".

Create an AnimationClip that moves the selected node from x=0 to x=300 in one second.

Persistent and structural changes require confirmation. A recommended workflow is:

1. Ask the client to inspect the current state and explain the planned change.
2. Review the target scene, nodes, assets, and paths.
3. Confirm the operation when the client requests permission.
4. Inspect the result in Cocos Creator and save the scene when appropriate.

Commit or back up important work before using mutation tools. Use a disposable scene and temporary assets for the first trial.

Tool management

The extension panel contains two tabs:

• Server controls the port, automatic startup, and server state.
• Tool management provides individual tool toggles and All, Core workflow, UI workflow, and Minimal presets.

Reducing the exposed tool set decreases the MCP tool definitions sent to the client. The preferences recovery tool always remains available. Clients that support tool-list change notifications refresh automatically; reconnect older clients if their tool list stays unchanged.

Settings are stored per project in library/cocos-mcp-community.settings.json.

Troubleshooting

• The client cannot connect: confirm that Cocos Creator is open, the extension is enabled, and the panel reports the server as running. Check that the client URL uses the same port.
• The tool list is outdated: reconnect the MCP client after saving Tool management changes.
• A scene action fails: open the target scene and try a read-only scene summary first.
• An edit is rejected: verify the target UUID or asset path and explicitly approve the requested write operation.
• Port already in use: choose another port between 1024 and 65535 in the Server tab, then update the client configuration.

Development

npm install
npm run check
npm run build
npm run test:ci

Command	Purpose
npm run check	Type-check without emitting build files
npm run build	Compile the extension to dist/
npm run test:regression	Run local regression checks
npm run test:smoke	Run regression and MCP transport/tool-discovery checks
npm run test:ci	Build and run the complete automated suite

The smoke suite does not mutate a Cocos project. Write integration tests should use disposable scenes and temporary assets.

Project structure

src/main.ts                 Extension lifecycle and panel messages
src/server/                 MCP transport, sessions, and tool registration
src/cocos/editor-bridge.ts  Cocos Editor integration
src/scene.ts                Scene-process operations
src/tools/                  Schema-validated MCP tools
src/panels/default/         Dockable extension panel
scripts/                    Regression and smoke tests

Contributing

Issues and pull requests are welcome. Please read CONTRIBUTING.md, preserve confirmation gates for persistent edits, and include tests and documentation for user-facing changes.

Acknowledgements

Thanks to the following open-source projects for reference and inspiration:

• caravanglory/cocos-mcp-server
• DaxianLee/cocos-mcp-server

License

Released under the MIT License.

This is an independent community project and is not an official Cocos product. Cocos and Cocos Creator are trademarks of their respective owners.