Cocos Creator MCP Server Plugin

📖 English 📖 中文

An MCP (Model Context Protocol) server plugin for Cocos Creator 3.5+. Enables AI assistants to interact with the Cocos Creator editor through a standardized protocol.

50 core tools covering 99% of editor functionality!

• 📖 Full Feature Guide (English)
• 📖 Full Feature Guide (中文)

Video Demo

<img width="503" height="351" alt="Demo Video" src="https://github.com/user-attachments/assets/f186ce14-9ffc-4a29-8761-48bdd7c1ea16" />

---

Requirements

• Cocos Creator 3.5.0+ (3.8.6+ recommended)
• Node.js (bundled with Cocos Creator)
• Git

---

Installation

For AI agents: Follow these steps sequentially. All commands run from the Cocos Creator project root directory.

Step 1: Verify Cocos Creator Project

Confirm the current directory is a Cocos Creator project:

# MUST have an assets/ directory
ls assets/

If assets/ does not exist, you are not in a Cocos Creator project root. Navigate to the correct directory first.

Step 2: Clone the Plugin

# Clone into extensions directory
mkdir -p extensions
git clone https://github.com/nicekid1/cocos-mcp-server.git extensions/cocos-mcp-server

If the plugin already exists, pull latest instead:

cd extensions/cocos-mcp-server && git pull && cd ../..

Step 3: Install Dependencies

cd extensions/cocos-mcp-server
npm install --production
cd ../..

Step 4: Start the MCP Server

The user must start the server from Cocos Creator editor:

1. Open the project in Cocos Creator
2. Go to Extensions > Cocos MCP Server
3. Click "Start Server"
4. Default port: 3000

Step 5: Verify Server is Running

curl http://127.0.0.1:3000/health

Expected: JSON response with status: "ok".

---

MCP Client Setup

For AI agents: After installation, register the MCP server in your client config. Pick the section matching your client.

Claude Code (CLI)

Run this command:

claude mcp add --transport http cocos-creator http://127.0.0.1:3000/mcp

OpenCode

Create or update opencode.json in the project root:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "cocos-creator": {
      "type": "remote",
      "url": "http://127.0.0.1:3000/mcp"
    }
  }
}

Claude Desktop

Add to Claude Desktop config file (claude_desktop_config.json):

{
  "mcpServers": {
    "cocos-creator": {
      "type": "http",
      "url": "http://127.0.0.1:3000/mcp"
    }
  }
}

Cursor / VS Code

Add to MCP settings:

{
  "mcpServers": {
    "cocos-creator": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

Other Clients

Protocol: HTTP transport, JSON-RPC 2.0. Endpoint: http://127.0.0.1:3000/mcp

Note: If you changed the port in the editor panel, replace 3000 with your configured port in all URLs above.

---

Troubleshooting

Problem	Solution
Server won't start	Check port 3000 is not in use: lsof -i :3000
Health check fails	Ensure server is started in Cocos Creator editor panel
Build errors	Run cd extensions/cocos-mcp-server && npm run build
Connection refused	Verify URL and port match editor panel settings
Tools not working	Ensure a scene is open in Cocos Creator

Enable Debug Log in the editor plugin panel for detailed logs.

---

License

Source code included for learning and secondary development. Commercial use and resale prohibited — contact author for commercial licensing.

Contact / Community

<img alt="QR Code" src="https://github.com/user-attachments/assets/a276682c-4586-480c-90e5-6db132e89e0f" width="400" height="400" />