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