Cocos MCP Community

English | 简体中文

Расширение для Cocos Creator 3.8+ на основе Model Context Protocol (MCP), созданное сообществом. Подключите совместимый ИИ-клиент, чтобы просматривать проект, открытый в Cocos Creator, и управлять им.

Расширение работает локально, прослушивает 127.0.0.1 и требует явного подтверждения для постоянных или структурных изменений.

Текущая версия: 0.2.3. Автоматизированный набор тестов проходит, а основные сценарии чтения и изолированной записи проверены в Cocos Creator 3.8.8.

Возможности

Сервер предоставляет 23 целенаправленных MCP-инструмента. Каждый инструмент группирует связанные действия, как клиенты получают сфокусированный спискинструментов, retaining широким охватм редактора.

Additional workflow features include session-aware Streamable HTTP, tool-list notifications, schema-validated input, confirmation gates, rollback-aware batch operations and project-specific tool preset.

Related MCP server: Cocos Creator MCP Server

Requirements

• Cocos Creator 3.8 or later

• Node.js 18 or later

• npm

• MCP client with Streamable HTTP support

Installation and usage

1. Install the extension

Clone the repository into the extensions directory of the Cocos project, 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 is already open, reload the extensions or restart the editor.

2. Launch MCP server

Open Extensions → 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 per-project port or enable automatic starting.

3. Connect MCP client

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

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

The remaining configuration differs. After the first connection, client_config can generate full entries for Claude Desktop, Cursor, VS Code, Windsurf.

After changing client configuration, restart or reconnect MCP client. If the server port changed on the Cocos panel, update the client URL accordingly.

4. Check the connection

Keep the target project and scene open in Cocos Creator, then request a read-only action from AI client, for example:

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 reports project or scene information, connection is ready.

5. Use editing workflows

You can define 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 explicit confirmation. Recommended workflow:

1. Ask the client to inspect current state and explain planned change.

2. Check the target scene, nodes, assets, paths.

3. Confirm the operation when client asks for permission.

4. View result in Cocos Creator and save scene if needed.

Do not "confusion. Use a disposable scene and temporary assets for first trial.

Manage tools

Tool panel contains two tabs:

• Server tab controls port, auto-install and server state.

• Tool managing tab includes individual tool switches and All, Core workflow, UI workflow, Minimal presets.

Reducing exposed toolset reduces number of MCP tool definitions sent to client. The client_config tool remains always available. Clients supporting tool list updates reload automatically; reconnect old clients if tool list does not change.

Settings are saved per project at library/cocos-mcp-community.settings.json.

Troubleshooting

• Client can’t connect: make sure Cocos Creator is open, the extension is enabled, and the panel reports server running. Ensure client URL uses same port.

• Tool list is outdated: reconnect MCP client after changes in the Tool management.

• Scene operation fails: open the target scene and try read-only scene summary first.

• Modify rejected: check target UUID or asset path and explicitly approve requested write operation.

• Port occupied: select another port between 1024 and 65535 in Server tab and update client configuration.

Development

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

Smoke tests do not change Cocos project. Integration tests should use temporary scene and temporary asset.

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

Contribution

Issues and pull requests are welcome. Please read CONTRIBUTING.md, preserve confirmation flows for persistent edits, and add tests and docs 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

Available under MIT License.

This is an independent community project and is not official Cocos product. Cocos and Cocos Creator are trademarks.