Skip to main content
Glama
cocos-mcp-pro

cocos-mcp-pro

by AzusaSubaru

cocos-mcp-pro

开源、跨 AI 客户端(TRAE / Cursor / Claude Code / Cline)的 Cocos Creator 3.8+ 社区 MCP 服务器,让 AI 能直接操控编辑器:查询节点树、搭建 UI、挂脚本连引用、校验场景、启动预览并回收运行时日志与截图。

状态:

阶段 0(真机 Spike)脚手架已完成

。MCP Server 与编辑器扩展已可构建运行,编辑器内部消息正在真实 Cocos 3.8 项目上逐项验证(见

docs/spike-checklist.md

)。

架构

AI 客户端 ──stdio / Streamable HTTP──▶ MCP Server(独立 Node 进程)

&#x20;                                         │ HTTP 127.0.0.1:<随机端口> + Bearer Token

&#x20;                                         ▼

&#x20;                         Cocos 扩展 main 进程(资源/项目/预览/诊断)

&#x20;                                         │ scene:execute-scene-script

&#x20;                                         ▼

&#x20;                         Cocos 扩展 scene 脚本(节点/组件/构建/校验)
  • 扩展启动后把 {port, token, cocosVersion} 写入项目 temp/.cocos-mcp.json,Server 自动发现;

  • 仅绑定 127.0.0.1,每会话随机 token,跨域预检拒绝,execute_script 类能力默认不开放。

Related MCP server: Cocos Creator MCP Server

仓库结构

包

说明

packages/shared

build_scene JSON schema、RPC 协议、错误码

packages/cocos-extension

Cocos Creator 编辑器扩展(main + scene 脚本),零运行时依赖,esbuild 预编译

packages/mcp-server

MCP 服务器(npm 包 cocos-mcp-pro),内置扩展副本(vendor/)与 init 命令

快速开始(开发版)

前置:Node.js 18+、pnpm(npm i -g pnpm)。

pnpm install

pnpm run build

1. 把扩展装进 Cocos 项目

node packages/mcp-server/dist/index.js init "D:/你的Cocos项目"

然后在 Cocos Creator 中:扩展 → 扩展管理器 → 项目(已安装),启用 cocos-mcp-bridge(首次启用建议刷新一次编辑器)。

2. 真机自检

node packages/mcp-server/dist/index.js selftest --project "D:/你的Cocos项目"

自检会探测 main/scene 两侧的编辑器消息与 API,输出 ✓/✗ 清单。任何 ✗ 都是适配层 packages/cocos-extension/src/adapter/messages.ts 的修正依据。

3. 在 AI 客户端接入

TRAE / Claude Code / Cline(stdio):

{

&#x20; "mcpServers": {

&#x20;   "cocos-mcp-pro": {

&#x20;     "command": "node",

&#x20;     "args": \["D:/cocosmcp/packages/mcp-server/dist/index.js"],

&#x20;     "env": { "COCOS\_MCP\_PROJECT": "D:/你的Cocos项目" }

&#x20;   }

&#x20; }

}

Cursor(Streamable HTTP):先运行 node dist/index.js --http --port 9118,再在客户端填 http://127.0.0.1:9118/mcp。

4. 预览日志 / 截图(可选)

需要 Playwright Chromium:

pnpm --filter cocos-mcp-pro exec playwright install chromium

\# 国内网络:

\# \$env:PLAYWRIGHT\_DOWNLOAD\_HOST="https://cdn.npmmirror.com/binaries/playwright"

已实现工具(45)

场景:scene_list/open/save/current/hierarchy/undo、spike_selftest

节点:node_find/get_info/create/delete/rename/set_transform

组件:component_add/remove/list/get_property/set_property/set_spriteframe/set_color/set_content_size、composite_setup_widget

复合:composite_create_label/create_sprite/create_button/attach_script/batch_set/build_hierarchy

资源:asset_list/search/create_folder/create_script/create_scene/refresh

编辑器:editor_get_project_info/preview_run/preview_stop/preview_logs/diagnostics、view_screenshot_game

校验:validate_references/layout/overlap/full_audit

构建:builder_build_scene(幂等、事务、失败回滚、可选自动保存)

知识库资源:cocos://knowledge/coordinate-system.md、cocos://knowledge/ui-rules.md。

开发命令

pnpm run build       # 构建全部包

pnpm run typecheck   # 类型检查

pnpm run test        # 单测(shared schema)

node packages/mcp-server/tests/stdio-smoke.mjs   # MCP 协议冒烟测试

设计文档

完整设计(工具规划、build_scene schema、路线图、风险登记册):docs/cocos-mcp-design.md。

法律

MIT License。本项目是社区项目,与厦门雅基软件(Cocos 官方)无隶属关系;Cocos、Cocos Creator 为其商标。

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to directly control the Cocos Creator 3.8.x editor via MCP protocol, providing over 130 tools for scene, node, component, asset, and project operations.
      44
      -
    • -
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables AI assistants to interact with the Cocos Creator 3.8+ editor through standardized protocols for scene, node, component, prefab, asset, project, debugging, and server operations.
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to directly control the Cocos Creator game editor via MCP protocol, supporting scene management, node manipulation, component attachment, and asset management.
      3
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI clients to inspect and operate the Cocos Creator project currently open, including scenes, nodes, assets, animations, and editor workflows via MCP.
      MIT