Content
# CocosMcp — Cocos Creator 2.4's MCP 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 **Cocos Creator 2.4** editor through [Model Context Protocol](https://modelcontextprotocol.io/): read/write scene nodes, add/delete resources, view console logs, run a debugging script...
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 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 validates parameters and packages envelopes, then forwards 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 need to access `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 litmus test. |
| `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 `packages/cocos-mcp/` in your Cocos Creator project. 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 【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 .
```
Or 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 file 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"
}
}
}
```
> Use forward slashes `/` or escaped backslashes `\\` on Windows. 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 【Extensions → Cocos MCP】).
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 get the last 20 logs.”
If these two steps succeed, it means the end-to-end connection is working.
## Add a New Tool
1. Add `your_thing.js` to `extension/handlers/`, exporting `{ name: 'your_thing', handle(params, ctx) { ... } }`. If scene operations are needed, add a `mcp:*` operation 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 calls a tool and returns `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 point; 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 Hijacks Editor.log for circular buffering
│ └── 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. The roadmap is 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`, same name in three places.
- **Resource operations do not bypass assetdb**: All resource write operations go through `Editor.assetdb.create/delete/refresh/setMetaInfo`, **prohibited** `fs.writeFileSync` to directly write project resources.
## License
[MIT](LICENSE). Referenced design ideas from [unity-mcp](https://github.com/CoplayDev/unity-mcp) (also MIT).
