Skip to main content
Glama
Cocos MCP Server

Cocos MCP Server

by andsky

Cocos MCP Server

通过 MCP 协议让 AI 助手(Claude、Cursor 等)直接操作 Cocos Creator 编辑器。

Version Cocos Creator License: MIT

这是什么

MCP(Model Context Protocol)是一种让 AI 助手调用外部工具的标准协议。本插件把 Cocos Creator 编辑器的操作暴露为 MCP 工具,AI 可以直接:

  • 创建/删除/移动节点

  • 挂载组件、设置属性

  • 管理预制体和资源

  • 控制场景视图

  • 运行预览和构建

简单说:你用自然语言描述需求,AI 帮你在编辑器里干活。

Related MCP server: cocos-mcp-server

快速开始

安装

把本目录放到项目的 extensions/ 下:

YourProject/extensions/cocos-mcp-server/

安装依赖并编译:

cd extensions/cocos-mcp-server
npm install && npm run build

重启 Cocos Creator,菜单栏出现 扩展 → Cocos MCP Server → Open Panel。

启动服务器

打开面板后点击 Start Server,默认监听 http://127.0.0.1:3000/mcp。

连接 AI 助手

Claude CLI:

claude mcp add --transport http cocos-creator http://127.0.0.1:3000/mcp

Claude Desktop / Cursor:

在 MCP 配置中添加:

{
  "mcpServers": {
    "cocos-creator": { "url": "http://127.0.0.1:3000/mcp" }
  }
}

连接成功后,AI 助手就能调用编辑器操作了。

工具一览

20 个统一工具,80+ 操作。每个工具通过 action 参数指定具体操作。

场景与节点

工具

操作

说明

scene_management

get, list, open, save, create, close, hierarchy

场景管理

node_lifecycle

create, delete, duplicate

节点增删复制

node_query

get, find, findBy, all

节点查找

node_transform

set, move, reset

位置/旋转/缩放

selection_manage

get, set, clear

编辑器选中状态

组件与 UI

工具

操作

说明

component_manage

add, remove, get, info, set

组件增删改查

ui_component

label, sprite, button, layout, widget, progress, editbox, slider, toggle

UI 控件快捷操作

script_manage

attach, create, compile, query, methods, execute, properties

脚本管理

资源与预制体

工具

操作

说明

asset_manage

import, create, delete, copy, move, info, query, list

资源 CRUD

asset_analyze

dependencies, unused, validate, batch, manifest

资源分析

prefab_lifecycle

create, update, revert, duplicate

预制体管理

prefab_browse

list, load, info, instantiate

预制体浏览与实例化

编辑器与调试

工具

操作

说明

project_manage

run, build, info, settings, refresh

项目控制

build_system

build, preview, settings, status, open, start, stop

构建流水线

scene_view

focus, align, gizmo, grid, mode, camera, reset, status

场景视图

preferences_manage

get, set, reset, export, import, open, list

编辑器偏好

debug_console

get, clear, execute

控制台访问

broadcast_message

listen, stop, send, log, clear, listeners

编辑器内部通信

server_info

status, connectivity, network, port, ip, restart, quit

服务器信息

animation_manage

clip, component, state, track, play, pause, stop, record

动画控制

使用示例

{ "tool": "node_lifecycle",  "arguments": { "action": "create", "name": "Player", "parentUuid": "uuid", "nodeType": "2DNode" }}
{ "tool": "ui_component",    "arguments": { "action": "label", "nodeUuid": "uuid", "text": "Hello", "fontSize": 24 }}
{ "tool": "animation_manage", "arguments": { "action": "play", "nodeUuid": "uuid", "clipName": "run", "loop": true }}
{ "tool": "script_manage",   "arguments": { "action": "attach", "nodeUuid": "uuid", "scriptPath": "db://assets/scripts/Player.ts" }}
{ "tool": "prefab_browse",   "arguments": { "action": "instantiate", "prefabPath": "db://assets/prefabs/Enemy.prefab", "parentUuid": "uuid" }}

配置

面板中可配置:

项

默认值

说明

端口

3000

HTTP 监听端口

自动启动

关闭

编辑器启动时自动开启服务器

调试日志

关闭

输出详细 MCP 通信日志

允许来源

*

CORS 来源限制

最大连接数

5

同时连接的 AI 客户端数

项目结构

source/
├── main.ts                  # 扩展入口
├── mcp-server.ts            # HTTP + MCP 协议服务
├── settings.ts              # 配置持久化(async fs)
├── scene.ts                 # 场景脚本(引擎上下文)
├── types/index.ts           # 共享类型 + VERSION
├── panels/default/          # 编辑器面板(Vue 3)
└── tools/
    ├── index.ts             # 工具注册表
    ├── unified-tool-base.ts # 抽象基类
    └── *.ts                 # 20 个工具文件

添加新工具

  1. 创建 source/tools/my-tool.ts,继承 UnifiedToolBase

  2. 在 source/tools/index.ts 的 TOOL_CLASSES 数组中注册

  3. npm run build — 工具自动注册到 MCP tools/list

详见 CLAUDE.md 中的"添加新工具"章节。

常见问题

Q: AI 连不上服务器? 检查编辑器面板中服务器状态是否为 running,端口是否被占用。

Q: 操作报权限错误? 确保场景已保存且未被其他进程锁定。

环境

  • Cocos Creator ≥ 3.8.6

  • TypeScript 5.x(开发依赖)

License

MIT

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 clients to control Cocos Creator editor projects, scenes, nodes, components, assets, Prefabs, building, and diagnostics via the MCP protocol.
      -