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.

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.

Related MCP server: Cocos Creator MCP Server

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

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.