Cocos Creator 2.x MCP Server

开源、免费、零依赖的 MCP (Model Context Protocol) 服务器，为 Cocos Creator 2.x 编辑器提供 AI 驱动的游戏开发能力。

支持 Claude Desktop、Cursor、Windsurf、Gemini CLI 等任何兼容 MCP 协议的 AI 客户端。

特性

• 15 个 MCP 工具，80+ 操作 — 覆盖场景、节点、组件、UI、动画、资源、预制体、构建全流程
• 零外部依赖 — 纯 Node.js 内置模块，无需 npm install
• 即装即用 — 复制到项目 packages/ 目录，打开编辑器即可
• 可视化设置面板 — 在编辑器内直接修改端口、开关服务
• AI 组件知识库 — 内置 16 个组件的完整属性定义和使用提示
• 自然语言意图分发 — 描述你想做的事，自动匹配对应工具

安装

将 cocos2x-mcp/ 文件夹复制到 Cocos Creator 2.x 项目的 packages/ 目录：

your-project/
  assets/
  packages/
    cocos2x-mcp/     <-- 复制到这里

打开编辑器，扩展自动加载，控制台输出：

[Cocos2x MCP] MCP Server running on http://localhost:3000/mcp

配置 AI 客户端

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

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

Cursor (项目根目录 .cursor/mcp.json):

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

修改端口

编辑器菜单 Cocos MCP Server > Settings 打开设置面板，可直接修改端口。

也可以手动编辑扩展目录下的 config.json：

{
  "port": 3000,
  "autoStart": true,
  "debugLog": false
}

修改后点击 Reload Config 或重启编辑器生效。

使用

在 AI 客户端中直接用自然语言描述你想做的事：

• "查看当前场景的节点树结构"
• "在 Canvas 下创建一个按钮，文字是'开始游戏'"
• "找到所有 Label 节点"
• "把 PlayerNode 的 x 改成 200"
• "帮我检查场景有没有缺失引用的问题"
• "cc.Widget 组件有哪些属性？怎么用？"

工具清单

场景与节点

UI 创建

资源与预制体

动画与视口

编辑器控制

校验与智能

详细操作说明

cocos_scene

cocos_node

cocos_component

cocos_composite

cocos_label

cocos_sprite

cocos_animation

cocos_prefab

cocos_asset

cocos_editor

cocos_builder

cocos_validate

cocos_knowledge

cocos_do

架构

AI 客户端 (Claude / Cursor / Gemini CLI)
    |  HTTP POST /mcp (JSON-RPC 2.0)
    v
main.js --- HTTP 服务器 (Electron 主进程)
    |
    v
src/tools/*.js --- 15 个工具模块
    |
    v
ipc-bridge.js --- Editor.Scene.callSceneScript (Promise 化)
    |
    v
scene-walker.js --- 场景脚本 (渲染进程, cc 全局可用)
    |
    v
Cocos Creator 2.x 引擎 API

两条执行路径：

• 场景操作（节点、组件、动画等）通过 Editor.Scene.callSceneScript 进入场景进程
• 编辑器操作（资源查询、场景保存、构建等）直接在主进程调用 Editor.assetdb 等 API

目录结构

cocos2x-mcp/
  package.json             # Cocos Creator 2.x 扩展清单
  config.json              # 服务器配置（端口、自动启动等）
  main.js                  # 扩展入口：HTTP 服务器 + 生命周期
  scene-walker.js          # 场景脚本：所有引擎操作的实现
  panel/
    index.js               # 设置面板 UI
  src/
    mcp-server.js           # MCP JSON-RPC 协议处理器
    tools/
      index.js              # 工具注册中心
      scene-tools.js        # cocos_scene
      node-tools.js         # cocos_node
      component-tools.js    # cocos_component
      composite-tools.js    # cocos_composite
      label-tools.js        # cocos_label
      sprite-tools.js       # cocos_sprite
      animation-tools.js    # cocos_animation
      prefab-tools.js       # cocos_prefab
      asset-tools.js        # cocos_asset
      editor-tools.js       # cocos_editor
      builder-tools.js      # cocos_builder
      validate-tools.js     # cocos_validate
      view-tools.js         # cocos_view
      knowledge-tools.js    # cocos_knowledge
      do-tools.js           # cocos_do
    utils/
      ipc-bridge.js         # Promise 化的 callSceneScript
      node-resolver.js      # 节点查找（UUID/路径/名称）
      component-map.js      # 31 个内置组件名称映射
      param-validator.js    # 参数校验

测试

# 自动化测试（需要 MCP 服务器运行中）
bash run_tests.sh

# 手动健康检查
curl http://localhost:3000/mcp

# 列出所有工具
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

已知限制

1. 大资源查询 — 项目资源量极大时，cocos_asset 查询可能超时
2. 预制体创建 — 当前仅支持实例化已有预制体，不支持从节点创建新预制体
3. SpriteFrame 加载 — 创建 Sprite 时无法直接指定图片资源（需通过 UUID 加载后赋值）

扩展开发

添加新工具

1. 在 src/tools/ 下创建 xxx-tools.js，导出 { definition, handler }
2. 在 src/tools/index.js 中 register() 注册
3. 如需场景操作，在 scene-walker.js 中添加对应方法
4. 重载扩展后生效

场景脚本方法格式

// scene-walker.js 中添加
myNewMethod: function (event, args) {
  // cc 全局可用
  var result = { /* ... */ };
  event.reply(null, result);  // 必须调用 event.reply
}

从工具层调用场景脚本

var ipcBridge = require('../utils/ipc-bridge');
ipcBridge.callSceneScript('myNewMethod', { param1: 'value' })
  .then(function (result) { /* ... */ });

License

MIT