mcp_for_cocos2.4

Cocos MCP — Cocos Creator 2.4 Bridge [](LICENSE) [](https://docs.cocos.com/creator/2.4/manual/en/) [](https://www.python.org/) [](https://modelcontextprotocol.io/) [](docs/plan.md) Let AI assistants (Claude Desktop / Claude Code / Cursor / Windsurf, etc.) directly operate the **Cocos Creator 2.4** editor through the [Model Context Protocol](https://modelcontextprotocol.io/): read and write scene nodes, add and delete resources, view console logs, run a debugging script, and more. Referenced the overall architecture of [unity-mcp](https://github.com/CoplayDev/unity-mcp) with Python (FastMCP) + editor plugin + WebSocket. > 📋 **Current Progress** and **Future Roadmap**: [`docs/plan.md`](docs/plan.md) > 🏗️ **Architecture Details**: [`docs/architecture.md`](docs/architecture.md) > ➕ **How to Add a New Tool**: [`docs/adding-tools.md`](docs/adding-tools.md) > 📊 **Unity-mcp Feature Set Comparison**: [`docs/unity-mcp-features.html`](docs/unity-mcp-features.html) (open locally) ## Architecture ``` AI Assistant (Claude / Cursor / ...) ↓ MCP stdio Python MCP Server (server/) ↓ WebSocket ws://127.0.0.1:6010/cocosmcp Cocos Creator 2.4 Editor Extension (extension/) ↓ Editor API + scene-script Scene, Resources, Console ``` * **Python Side**: `server/` is a FastMCP server. Each tool module (`get_project_info`, `read_console`, `manage_asset`, `manage_scene`, `manage_node`, `execute_script`) only performs parameter validation and envelope packaging, forwarding commands to the extension. * **Editor Side**: `extension/` is a standard Cocos Creator 2.4 package. `main.js` starts a `ws` server in the main process and dispatches each frame to `handlers/<command>.js`. Operations that require access to `cc.director` / nodes are handed over to `scene-script.js` via `Editor.Scene.callSceneScript('cocos-mcp', ...)`. ## Implemented MCP Tools (MVP) | Tool | Purpose | | ------------------- | ------------------------------------------------------------------- | | `get_project_info` | Project path, editor version, scene list, available commands - a quick check. | | `read_console` | Read / clear `Editor.log/info/warn/error` circular buffer. | | `manage_asset` | `list / info / read / create / delete / refresh` (based on `Editor.assetdb`). | | `manage_scene` | `list / current / open / save` scenes. | | `manage_node` | `tree / get / set_property / create / delete / add_component / selection`, requires a scene to be open. | | `execute_script` | Run a JS script in the main process or scene context. **Powerful but dangerous**, please obtain user permission before calling. | Future additions: `manage_prefab` / `manage_component` (batch by name) / `build` / `hot_update` / `manage_proto` (connect to your project's `BuildProto.cmd` process), etc. ## Installation ### 1. Install Editor Extension Copy (or soft link) `extension/` to the Cocos Creator project's `packages/cocos-mcp/`. Replace `<YOUR_COCOS_PROJECT>` with your actual Cocos project path: ```cmd xcopy /E /I extension <YOUR_COCOS_PROJECT>\packages\cocos-mcp ``` Enter `extension/` and install runtime dependencies (only once): ```cmd cd /d <YOUR_COCOS_PROJECT>\packages\cocos-mcp npm install ``` Open Cocos Creator and restart the editor to discover the new package. You should see the menu 【Extensions】→【Cocos MCP】. The bridge will automatically start and listen on `ws://127.0.0.1:6010/cocosmcp`. ### 2. Install Python Server Requires Python 3.10+. Recommended to use [uv](https://github.com/astral-sh/uv) or venv: ```cmd cd server python -m venv .venv .venv\Scripts\activate pip install -e . ``` Alternatively, use uv: ```cmd cd server uv pip install -e . ``` Run the server to verify: ```cmd python -m main --transport stdio ``` Normal output (written to stderr) should include `cocos-mcp v0.1.0 starting` and `bridge target: ws://127.0.0.1:6010/cocosmcp`. Press Ctrl+C to exit. ### 3. Connect Server to Claude Desktop / Claude Code Refer to [docs/claude-mcp-config-example.json](docs/claude-mcp-config-example.json). Claude Desktop configuration example: ```json { "mcpServers": { "cocos": { "command": "<ABS_PATH_TO_REPO>/server/.venv/Scripts/python.exe", "args": ["-m", "main", "--transport", "stdio"], "cwd": "<ABS_PATH_TO_REPO>/server/src" } } } ``` > On Windows, use forward slashes `/` or escaped backslashes `\\`. On macOS/Linux, replace `Scripts` with `bin` and remove the `.exe` extension. Claude Code (`~/.claude.json` or `claude mcp add` command) is similar. ## First Run 1. Open your project in Cocos Creator and see the “Cocos MCP” panel at the bottom (or open it from the 【Extensions → Cocos MCP】 menu). 2. The panel should show “Status: Running” and the URL `ws://127.0.0.1:6010/cocosmcp`. 3. Ask Claude: “Call `get_project_info` to see the project path.” - it should return `projectPath`, `editorVersion`, and the initial scene list. 4. Then ask: “Call `read_console` to fetch the last 20 logs.” If these two steps work, it means the end-to-end connection is established. ## Adding a New Tool 1. Add `your_thing.js` to `extension/handlers/`, exporting `{ name: 'your_thing', handle(params, ctx) { ... } }`. If scene operations are required, add a `mcp:*` op in `scene-script.js` and forward it using `Editor.Scene.callSceneScript`. 2. Add `your_thing.py` to `server/src/services/tools/`, decorated with `@cocos_mcp_tool`, and implement the function body with `await call_bridge("your_thing", params)`. 3. Restart the editor (to reload the extension) and restart the Python server. The new tool will automatically appear in the MCP list. See [docs/adding-tools.md](docs/adding-tools.md) for a more detailed template. ## Troubleshooting * **Claude tool call return `bridge_unavailable`**: Check if the panel shows “Status: Stopped”; click 【Start】or check if the port is occupied. * **`ws module not installed`**: Run `npm install` in `extension/`. * **`manage_node` reports `no scene is currently open`**: First, `manage_scene action=open url=...`. * **Python side import error**: Ensure you run `python -m main` in the `server/src/` directory or add `src/` to `PYTHONPATH`. ## Directory Structure ``` cocosMcp/ ├── server/ Python MCP server (FastMCP) │ ├── pyproject.toml │ └── src/ │ ├── main.py Entry point │ ├── core/config.py Configuration (host/port/timeout) │ ├── transport/ws_client.py WebSocket client + request-response mapping │ ├── services/ │ │ ├── registry.py @cocos_mcp_tool decorator │ │ └── tools/ Each .py = one MCP tool │ └── utils/module_discovery.py ├── extension/ Cocos Creator 2.4 editor extension │ ├── package.json │ ├── main.js Main process entry; starts WS server │ ├── scene-script.js Scene context operations (cc.director available) │ ├── handlers/ Each .js = one command │ ├── lib/ws-server.js WS wrapper │ ├── lib/console-hook.js Hijack Editor.log for circular buffer │ └── panel/index.js Status panel in the editor ├── docs/ │ ├── architecture.md │ ├── adding-tools.md │ └── claude-mcp-config-example.json ├── install.cmd Windows one-click installation prompt ├── CLAUDE.md Work guidelines for AI └── README.md ``` ## Contribution This is an MVP that is still rapidly iterating, with the roadmap in [`docs/plan.md`](docs/plan.md). Feel free to raise issues to discuss ideas or submit PRs to add tools - see [`docs/adding-tools.md`](docs/adding-tools.md) for the process. Two coding style rules (same as [`CLAUDE.md`](CLAUDE.md)): - **Symmetrical naming**: `tools/<name>.py` ↔ bridge command `<name>` ↔ `handlers/<name>.js`, with the same name in all three places. - **Resource operations do not bypass assetdb**: All resource write operations go through `Editor.assetdb.create/delete/refresh/setMetaInfo`, **prohibiting** direct writes with `fs.writeFileSync`. ## License [MIT](LICENSE). Referenced design ideas from [unity-mcp](https://github.com/CoplayDev/unity-mcp) (also MIT).