Cocos MCP 連線失敗排查：Cursor 看不到 cocos-creator 怎麼辦

把 Cocos MCP 接到 Cursor（或其他 MCP 用戶端）時，最常見的卡點不是「不會寫提示」，而是橋接根本沒連上：編輯器裡服務未運行，或 AI IDE 裡看不到 cocos-creator。

若你的說法是「Cursor 壞了 / 連不上」，可先從 Cursor 側症狀入手：Cursor 連上 Cocos Creator MCP 後壞了？。

若還不確定 MCP 能做什麼、和「Cocos Creator AI」差在哪，可先讀：Cocos Creator MCP 是什麼。

本文按症狀 → 原因 → 處理步驟排查，涵蓋 Creator 2.x 與 3.x。安裝全流程見：

• Cocos Creator 3.x MCP 安裝教學
• Cocos Creator 2.x MCP 安裝教學

下文以 Cursor 為例；Claude Code、Codex 等用戶端的 MCP 重載與設定核對方式類似。

先確認：你卡在哪一層

MCP 鏈路可以拆成四層。任一層失敗，表現都會像「連不上」：

1. 外掛已進專案且已啟用
        ↓
2. 面板已啟用（帳號/啟用碼）
        ↓
3. MCP Server 顯示「運行中」（本機 localhost）
        ↓
4. AI IDE 已寫入設定且 MCP 列表顯示已連線

你看到的現象	優先查
沒有「擴展 → Cocos MCP Server / MCP Server」選單	第 1 層：包版本、匯入路徑、是否重啟
能打開面板，但無法啟動服務 / 一直提示未啟用	第 2 層：帳號與啟用碼
點了「啟動服務」，沒有「運行中」	第 3 層：埠、防火牆、啟用狀態
Creator 裡已是「運行中」，Cursor 裡沒有 cocos-creator	第 4 層：快速配置、MCP 重載、設定檔
Cursor 裡顯示已連線，但列不出場景節點	驗證方式、工具勾選、是否打開了正確專案

症狀 A：選單裡根本沒有 MCP 擴充

可能原因

1. 2.x / 3.x 壓縮包混用
2. 3.x 未在擴展管理中匯入，或匯入後仍為停用
3. 2.x 外掛未放在 packages/<外掛名>/，或多巢狀了一層解壓目錄
4. 2.x 放入 packages 後未完全重啟 Creator

處理步驟

若你是 Creator 3.x：

1. 確認下載頁是 Cocos MCP 3.x，不是 2.x 包
2. 打開專案 → 擴展 → 擴展管理 → 匯入擴展 → 選擇 3.x 壓縮包
3. 列表中確認 cocos-mcp-server 已啟用；若為停用，點啟用
4. 仍無選單時：關閉 Creator 後重新打開同一專案

若你是 Creator 2.x：

1. 確認下載頁是 Cocos MCP 2.x
2. 解壓後目錄應類似：

你的專案根目錄/
  packages/
    <外掛名>/          ← 外掛檔案直接在這一層
      package.json     ← 應能在此路徑看到（名稱以實際包為準）

3. 錯誤示例（多套一層）：

packages/
  xxx-mcp-unzip/
    <外掛名>/
      package.json

4. 修正路徑後，結束並重新啟動 Creator（不是只重新整理場景），再看 擴展 → MCP Server

症狀 B：能開面板，但啟用失敗或無法啟動

可能原因

• 帳號未開通對應 Pro 權益
• 啟用碼過期、信箱不匹配
• 未啟用就點了「啟動服務」

處理步驟

1. 打開 MCP 面板（3.x：擴展 → Cocos MCP Server → Open Mcp Panel；2.x：擴展 → MCP Server）
2. 任選一種方式完成啟用：
   • VberAI 帳號 + 密碼
   • 信箱 + 啟用碼
3. 在官網帳號中心核對方案 / 啟用碼狀態後，回到面板重試
4. 啟用成功後再進入 MCP Server 設定頁點擊「啟動服務」

未啟用時，多數情況下服務無法進入「運行中」。這不是 Cursor 的問題，先停在編輯器側解決。

症狀 C：點了「啟動服務」，沒有「運行中」

可能原因

1. 仍未啟用（見症狀 B）
2. 埠被占用（3.x 預設常見為 3000；2.x 以面板顯示為準）
3. 本機防火牆 / 安全軟體攔截了 localhost 監聽

處理步驟

1. 在 MCP Server 設定頁確認埠號（下文以 3000 為例，請改成你面板上的值）
2. 在本機終端機檢查埠是否已被占用：

macOS / Linux：

lsof -iTCP:3000 -sTCP:LISTEN

Windows（PowerShell）：

netstat -ano | findstr :3000

3. 若已有其他行程占用：
   • 結束占用行程，或
   • 在 MCP 面板改用空閒埠，再點「啟動服務」
4. 確認防火牆未攔截對本機 127.0.0.1 的存取（MCP 不要對映到公網）
5. 面板出現 「運行中」 後，再去做 Cursor 側設定

症狀 D：Creator 已「運行中」，Cursor 看不到 cocos-creator

這是「連線失敗」裡占比最高的一類：編輯器側正常，用戶端未吃到設定。

處理步驟（按順序做）

1. 回到 Creator，確認 MCP 面板仍為「運行中」（改埠或重啟編輯器後，服務可能已停）
2. 打開 工具管理，確認需要的工具已勾選
3. 打開 快速配置 → 選擇 Cursor → 自動配置，直到介面顯示 已配置
4. 打開 Cursor → MCP / 工具列表：
   • 應出現 cocos-creator（或以面板實際服務名為準）
   • 若沒有：在 Cursor 中 重新載入 MCP（或重啟 Cursor）後再看
5. 仍沒有：核對 Cursor 的 MCP 設定是否寫入了本機橋接位址（通常指向 127.0.0.1 與面板埠）

設定經「自動配置」寫入後，內容形態因 Cursor 版本而異，大致會包含服務名與本機連線資訊。人工檢查時關注：

• 服務名是否對應 Cocos MCP（如 cocos-creator）
• 位址是否為 127.0.0.1（或 localhost），埠是否與 Creator 面板一致
• 是否誤寫成區網 IP 或公網位址

改完設定後，必須再執行一次 MCP 重載，否則介面仍顯示舊狀態。

其他 AI IDE

在「快速配置」裡換成 Claude Code、Codex、Windsurf、Cline 等目標用戶端，重複「自動配置 → 在用戶端重載 MCP」。不要假設「配過 Cursor 就等於所有 IDE 已連通」。

症狀 E：顯示已連線，但列不出場景 / 改不動節點

可能原因

1. Creator 裡打開的專案 / 場景與提問假設不一致
2. 工具管理裡相關能力未勾選
3. 只驗證了「磁碟上的腳本」，沒有驗證「編輯器上下文」

驗證步驟

在 Cursor 中先發一條唯讀指令：

列出目前 Cocos Creator 打開場景的根節點名稱。

結果	含義
回覆與編輯器層級一致	橋接正常，可繼續小範圍寫入測試
明確報錯 / 無工具	回到症狀 C/D：服務與 MCP 列表
胡亂編造節點名	多半未真正調到 MCP，檢查連線狀態與工具勾選

再做一次小範圍寫入（新建臨時節點並刪除），確認權限符合預期。大改前先提交版本。

2.x / 3.x 差異速查

項目	Creator 3.x	Creator 2.x
產品頁	cocos（3.x）	cocos2x
安裝方式	擴展管理 → 匯入擴展	解壓到專案 packages/
安裝後	列表啟用即可	必須重啟 Creator
壓縮包	僅用 3.x 包	僅用 2.x 包
詳細步驟	3.x 安裝教學	2.x 安裝教學

混用壓縮包時，表現常常是「選單沒有」或「匯入失敗」，優先用本表排除。

推薦排查順序（5 分鐘清單）

按順序打勾，多數連線問題會落在前四項：

1. Creator 大版本與 MCP 壓縮包一致（2.x ↔ 2.x，3.x ↔ 3.x）
2. 擴充已啟用 / packages 路徑正確，且 2.x 已重啟過
3. 面板已啟用成功
4. 面板顯示 運行中；埠無衝突
5. 已對目前 IDE 執行「快速配置 → 自動配置」
6. 已在 AI IDE 中重載 MCP，列表出現 cocos-creator
7. 唯讀提問能列出目前打開場景的根節點

仍失敗時記錄這些資訊

向支援或同事求助時，一併提供：

• Creator 精確版本（如 3.8.x / 2.4.x）
• MCP 包類型（2.x 或 3.x Pro）
• 面板是否「運行中」、目前埠號
• AI IDE 名稱與版本、MCP 列表截圖
• 唯讀驗證提示的原文與回覆

橋接僅應監聽本機；不要把 MCP 埠暴露到公網。

相關文件

• Cocos Creator 3.x MCP 安裝
• Cocos Creator 2.x MCP 安裝
• Cocos Creator MCP 影片設定教學
• 三引擎怎麼選：Godot MCP vs Unity MCP vs Cocos MCP