Cocos MCP Connection Troubleshooting: Cursor Doesn’t Show cocos-creator

When wiring Cocos MCP to Cursor (or another MCP client), the usual blocker is not “bad prompts”—it is that the bridge never connects: the editor server is down, or the AI IDE never lists cocos-creator.

If your phrasing is “Cursor is broken / won’t connect,” start from Cursor-side symptoms: Cursor Broken After Cocos Creator MCP.

If you still need the capability picture—and how MCP differs from vague “Cocos Creator AI”—read What Is Cocos Creator MCP first.

This guide follows symptom → cause → fix for Creator 2.x and 3.x. Full install flows:

• Cocos Creator 3.x MCP install
• Cocos Creator 2.x MCP install

Examples use Cursor; Claude Code, Codex, and similar clients follow the same reload / config checks.

First: which layer failed?

The MCP path has four layers. Failure at any layer looks like “cannot connect”:

1. Extension installed and enabled
        ↓
2. Panel activated (account / license code)
        ↓
3. MCP Server shows Running (localhost)
        ↓
4. AI IDE config written and MCP list shows connected

What you see	Check first
No Extension → Cocos MCP Server / MCP Server menu	Layer 1: package version, import path, restart
Panel opens but cannot start / stays unactivated	Layer 2: account and license
Clicked Start but never Running	Layer 3: port, firewall, activation
Creator shows Running, Cursor has no cocos-creator	Layer 4: quick config, MCP reload, config file
Cursor shows connected but cannot list scene nodes	Verification prompt, tool toggles, correct project open

Symptom A: No MCP extension in the menu

Likely causes

1. Mixed 2.x / 3.x packages
2. 3.x: not imported in Extension Manager, or still disabled
3. 2.x: not under packages/<plugin-name>/, or an extra unzip nesting level
4. 2.x: files placed but Creator was not fully restarted

Fixes

Creator 3.x:

1. Download from Cocos MCP 3.x—not the 2.x pack
2. Open the project → Extension → Extension Manager → Import → select the 3.x zip
3. Confirm cocos-mcp-server is enabled; enable it if disabled
4. If the menu is still missing: quit Creator and reopen the same project

Creator 2.x:

1. Download from Cocos MCP 2.x
2. After unzip, the tree should look like:

your-project-root/
  packages/
    <plugin-name>/          ← plugin files directly here
      package.json          ← should exist at this path (name per package)

3. Wrong nesting example:

packages/
  xxx-mcp-unzip/
    <plugin-name>/
      package.json

4. Fix the path, then quit and restart Creator (not just refresh the scene). Check Extension → MCP Server.

Symptom B: Panel opens, but activation fails or service won’t start

Likely causes

• Account lacks matching Pro entitlement
• License code expired or email mismatch
• Clicked Start before activation

Fixes

1. Open the MCP panel (3.x: Extension → Cocos MCP Server → Open Mcp Panel; 2.x: Extension → MCP Server)
2. Activate with either:
   • VberAI account + password
   • Email + license code
3. Confirm plan / code on the official account center, then retry in the panel
4. Only after activation open MCP Server settings and click Start

Without activation, the server usually never reaches Running. Fix the editor side before blaming Cursor.

Symptom C: Clicked Start, but never Running

Likely causes

1. Still not activated (see symptom B)
2. Port in use (3.x often defaults to 3000; 2.x follows the panel)
3. Firewall / security software blocks localhost listen

Fixes

1. Note the port on the MCP Server settings page (examples below use 3000—replace with your panel value)
2. Check whether something is already listening:

macOS / Linux:

lsof -iTCP:3000 -sTCP:LISTEN

Windows (PowerShell):

netstat -ano | findstr :3000

3. If another process holds the port:
   • stop that process, or
   • pick a free port in the MCP panel, then Start again
4. Ensure firewall allows 127.0.0.1 (do not expose MCP to the public internet)
5. When the panel shows Running, configure the AI IDE

Symptom D: Creator is Running, Cursor has no cocos-creator

Most “connection failed” reports land here: editor OK, client never ingested config.

Fixes (in order)

1. In Creator, confirm the MCP panel is still Running (port changes or editor restarts may stop it)
2. Open Tool Manager and enable the tools you need
3. Open Quick Config → choose Cursor → Auto Config until the UI shows Configured
4. In Cursor → MCP / tools list:
   • You should see cocos-creator (or the name shown in the panel)
   • If missing: Reload MCP (or restart Cursor) and check again
5. Still missing: verify Cursor’s MCP config contains the local bridge (127.0.0.1 + the panel port)

Auto Config output varies by Cursor version. When inspecting manually:

• Service name matches Cocos MCP (e.g. cocos-creator)
• Host is 127.0.0.1 or localhost, port matches Creator
• Not a LAN or public IP by mistake

After any config edit, reload MCP again or the UI keeps the old state.

Other AI IDEs

In Quick Config, pick Claude Code, Codex, Windsurf, Cline, etc., then Auto Config → reload MCP in that client. Configuring Cursor does not connect every IDE.

Symptom E: Shows connected, but cannot list scene / edit nodes

Likely causes

1. Open project / scene in Creator does not match what you asked about
2. Needed tools unchecked in Tool Manager
3. You only verified “files on disk,” not editor context

Verification

Send a read-only prompt in Cursor:

List the root node names of the scene currently open in Cocos Creator.

Result	Meaning
Matches the Hierarchy	Bridge OK; try a small write next
Clear error / no tools	Return to symptoms C/D
Invented node names	MCP likely unused; check connection and tool toggles

Then try a small write (create a temporary node and delete it). Commit before large edits.

2.x vs 3.x quick table

Item	Creator 3.x	Creator 2.x
Product page	cocos (3.x)	cocos2x
Install	Extension Manager → Import	Unzip into project packages/
After install	Enable in the list	Must restart Creator
Package	3.x only	2.x only
Full steps	3.x install	2.x install

Mixed packages often show as “no menu” or “import failed”—use this table first.

Recommended order (5-minute checklist)

Tick in order; most failures sit in the first four:

1. Creator major version matches the MCP zip (2.x ↔ 2.x, 3.x ↔ 3.x)
2. Extension enabled / packages path correct; 2.x restarted
3. Panel activated successfully
4. Panel shows Running; port free
5. Quick Config → Auto Config for the current IDE
6. Reloaded MCP in the AI IDE; cocos-creator listed
7. Read-only prompt lists roots of the currently open scene

If it still fails, capture this

When asking support or a teammate, include:

• Exact Creator version (e.g. 3.8.x / 2.4.x)
• MCP pack type (2.x or 3.x Pro)
• Whether the panel is Running, and the port
• AI IDE name/version and MCP list screenshot
• Exact read-only prompt and reply

Keep the bridge on localhost only; do not publish the MCP port.

Related docs

• Cocos Creator 3.x MCP install
• Cocos Creator 2.x MCP install
• Cocos Creator MCP video setup
• Engine pick guide: Godot MCP vs Unity MCP vs Cocos MCP