Skip to main content
Glama
cocos-mcp-community

cocos-mcp-community

by chang0022

Cocos MCP Community

English | 简体中文

一个由社区构建的 Model Context Protocol (MCP) 扩展,适用于 Cocos Creator 3.8+。连接兼容的 AI 客户端后,即可检查并操作 Cocos Creator 当前打开的项目。

该扩展在本地运行,监听 127.0.0.1,对于持久性或结构性更改,需要明确的二次确认。

当前版本:0.2.3。自动化测试套件已通过,主要的读取和隔离写入工作流已在 Cocos Creator 3.8.8 上验证。

功能

该服务器暴露 23 个面向意图的 CP 工具。每个工具都将相关操作分组,使客户端获得聚焦的工具列表,同时保留编辑器的广泛覆盖能力。

工具

能力说明

project

读取项目信息和资源摘要;查询或更新项目配置

scene

检查当前活动场景和层级结构;打开、保存或将场景另存为

node

查找、检查、创建、更新、复制、拷贝、剪切、粘贴、重置、重设父级或删除节点

component

列出、添加、移除、检查、编辑或重置组件;编辑数组和 Button 事件;应用文本样式

asset

检查了 AssetDB,列出并检查资源,读取安全文本资源、导入、创建、保存、复制、移动、刷新、重新导入或删除

prefab

列出并检查 Prefab,查找用途,实例化关联或非关联副本,复制或删除资产,并恢复实例

snapshot

捕获和恢复层级快照;开始、提交或中止作用域结构事务进度

builder

一次性创建经过验证的节点树,或完整的 Canvas/Panel/Title/Button UI 场景

validation

检查层级结构和 UI 问题;验证引用;分析依赖、循环、缺失项和孤立级别

capture

捕获结构化布局数据、Camera 渲染的 PNG 或裁剪后的本地 Preview 画布 PNG

animation

创建、保存、批量生成、检查和增量编辑 AnimationClip;绑定并控制动画片段

viewport

读取设计分辨率与编辑视图状态;聚焦或对齐节点;配置 2D、网格、Gizmo、图标选项

editor

读取编辑器上下文、选择状态、脏标记、就绪状态、Creator 控制栏条目、项目日志和 Preview 错误

often

检查 Preview 网络连接、启动支持的 Preview 目标、重新发布 Preview、停止 Game View、点击本地 Preview 按钮

preview

检查 Preview 的网络连接,启动支持的 Preview 目标,重启 Preview,停止 Game View,点击本地 Preview 按钮

preview? — wait, I listed two? No. Let me re-examine. In the original there's only one "preview" row. I accidentally wrote preview and then repeated. I need to remove the duplicated duplic.

Let me fix that row in my output:

| ----- | preview 检查 | Preview networking, start supported Preview targets, reload preview, stop Game View, click local Preview buttons |

I'll write: | preview | 检查 Preview 网络连接、启动支持的 Preview 目的 ss...

Hmm "Preview targets" - targets. OK.

Continue:

| ui | 确保场景有一个 Canvas,并用于创建模板、Layout 容器、对话框、列表、导航栏或设置界面 | | spine | 为 sp.Skeleton 组件指定 Spine数据,并列出、播放、排队或清除动画 | | font | 列出项目字体,并将项目字体或系统字体应用到 cc.Label | | reference_image | 列出 SpriteFrame,并从某个项目资源 in which place in-scene reference image 将 reference frame 放到场景中 | | environment | 检查引擎和原生平台路径、设备信息、编辑器网络、编程配置与外置插件 | | knowledge | 按主题检索内置的 Cocos 工作指导指南 | | server | 逐项读取本地服务状态和历史操作元数据 | | preferences | 检查、禁用、启用或重置项目本地的工具选择 | | client_config | 为 Claude Desktop、Cursor、VS Code 或 WindSurf 生成客户端配置 |

Now, I must ensure my final table has exactly these rows: project, scene, node, component, asset, prefab, snapshot, builder, validation, capture, animation, viewport, editor, preview, ui, spine, font, reference_image, environment, knowledge, server, preferences, client_config = 23 rows. Good.

Additional features paragraph: "Additional workflow features include: Streamable HTTPStorage..." as above.

Let me write the final answer now in one clean pass, carefully avoiding repetition errors. Also ensure all GXP tokens appear.

One more check: the "Run smoke unit" paragraph: "The smoke suite does not mutate a Cocos project. Write integration tests should use disposable scenes and temporary assets." Hmm, in the final I'll translate as "冒烟测试不会改动 Cocos 项目。编写集成测试时应使用一次性场景和临时资源。"

Also the "Current version" line: keep 0.2.3.

Also "Model Context Protocol (MCP)" — In first paragraph, the link text in Chinese should be "模型上下文协议(MCP)" perhaps instead of keeping English "Model Context Protocol (MCP)". The instruction says keep product/project names; "Model Context Protocol" is a protocol name — keep English. So I'll write "一个社区构建的 Model Context Protocol (MCP) 扩展".

Final translation, assembled:


Cocos Creator Community

English | 简体中文

一个由社区构建的 Model Context Protocol (MCP) 扩展建成于 Cocos Creator 3.8+。连接兼容的 AI 客户端后,即可检查并操作 Cocos Creator 当前打开的项目。

该扩展在本地运行、在 127.0.0.1 上监听,并且对于持久性活。Require explicit confirmation。

Hmm — "persistent or structural changes" = persistent与结构性 changes。

Let me write the full thing:


Cocos MCP Community

English | 简体中文

一个由社区构建的 Model Context Protocol (MCP) 扩展,适用于 Cocos Creator 3.8+。连接兼容的 AI 客户端后,即可检查并操作 Cocos Creator 当前打开的项目。

该扩展运行在本地,监听 127.0.0.1,并且对于持久性或结构性的更改需要明确确认。

当前版本:0.2.3。自动化测试套件已通过,主要的读取和隔离写入流程已在 Cocos Creator 3.8.8 上验证。

Related MCP server: Cocos Creator MCP Server

功能

服务器暴露了 23 个面向意图的 MCP 工具。每个工具对相关操作进行分组,使客户端获得一个集中的工具列表,同时保持广泛的编辑器覆盖范围。

[table]

其他工作流功能包括:会话感知 Streamable HTTP、工具列表变更通知、Schema 校验输入、确认门、支持回滚的批量操作,以及项目本地工具预设。

环境要求

  • Cocos Creator 3.8 或更高版本

  • Node.js 18 或更高版本

  • npm

  • 支持 Streamable HTTP 的 MCP 客户端

安装与使用

1. 安装扩展

将仓库克隆到 Cocos 项目的 extensions 目录,安装依赖并构建:

cd /path/to/YourCocosProject/extensions
git clone <repository-url> cocos-mcp-community
cd cocos-mcp-community
npm ci
npm run build

在 Cocos Creator 中打开项目。如果编辑器已经打开,请重新加载扩展或重新启动编辑器。

2. 启动 MCP 服务器

打开 Extension → Cocos Community,选择 Start server。佑。

http://127.0.0.1:3100/mcp

面板会显示当前端点和服务状态。也可更改项目本地端口,或启用自动启动。

3. 连接 MCP 客户端

在客户端 MCP 设置中添加一个 Streamable HTTP 服务器。通用配置为:

{
  "type": "http",
  "url": "http://127.0.0.1:3100/mcp"
}

Cocos configure it — "配置方式因客户端而异。首次连接后,client_config 工具可生成 Claude、Cursor、VS Code、按 、Windsurf 完整配置条目。"

修改配置后请重启 MCP 客户端。若在 Cocos 面板中更换了服务器端口,也请更新客户端 URL。

4. 验证连接

在 Cocos Creator 中保持目标项目和场景打开,然后请 AI 客户端执行一个只读操作,例如:

Summarize the current Cocos scene hierarchy.
List the assets under db://assets and report any missing references.
Check the current editor and Preview errors without changing the project.

如果客户端能返回项目或场景信息,则连接就绪。

5. 使用编辑工作流

你可以用自然语言描述编辑任务。例如:

Create a Canvas with a centered panel, a title, and a button in the current scene.
Set the selected Label font size to 32 and change its text to "Play".
Create an AnimationClip that moves the selected node from x=0 to x=300 in one second.

持久和结构性更改需要确认。推荐的工作流程:

  1. 让客户端检查当前状态并说明计划中的更改。

  2. 检查目标场景、节点、资源路径和路径。

  3. 当客户端请求许可时确认为。

  4. 在 Cocos Creator 中检查结果,适时保存场景。

在使用更改工具之前,提交或备份重要工作。第一次尝试时使用一次性场景和临时资源。

工具管理

系统面板包含两个标签页:

  • Server 控件的端口、串,自动启动与服务器状态。

  • Tool management 提供单个工具开关和 All、Core workflow、UI workflow、Minimal 预设。

减少暴露的工具集可减少发送到客户端的 MCP tool 定义。preferences 恢复工具始终可用。支持工具列表变更跨界刷新自动刷新;如果工具列表始终未拆,请重新连接旧客户客户端。

设置按存储在每个项目的中 library/cocos-mcp-community.settings.json。

调试

  • 客户端无法连接: 请确认 Cocos Creator 已打开,拓展已启用,并且面板显示服务器正在运行。同时确认 URL 的端口与服务器的端口一致。 *工具列表过期: 保存在工具管理中进行的设置后,请重新连接 MCP client.

  • 场景操作失败: 请重新打开目标场景,先于是试一个只读场景摘要。

  • 编辑被拒: 验证目标 UUID 或 asset 路径,并明确批准所请求的写操作。

  • 端口冲突: 在 Server 选项卡中另选一个 1024 到 65535 之间的端口,然后重新创建 client 配置。

开发

npm install
npm run check
npm run build
npm run test:ci

命令

说明

npm run check

无产构建 -- 文件检查类型

npm run build

将扩展编译到 dist/

npm run test:regression

运行本地回归检查

npm run test:smoke

运行回归以及 MCP传输/工具发现检查

npm run test:ci

构建并运行完整自动测试套件

冒烟测试套件不会修改任何 Cocos 项目。编写集成测试时应使用一次性场景和临时资源。

项目结构

src/main.ts                 Extension lifecycle and panel messages
src/server/                 MCP transport, sessions, and tool registration
src/cocos/editor-bridge.ts  Cocos Editor integration
src/scene.ts                Scene-process operations
src/tools/                  Schema-validated MCP tools
src/panels/default/         Dockable extension panel
scripts/                    Regression and smoke tests

贡献

欢迎提交 Issue 和 Pull Request。请阅读 CONTRIBUTING.md 来了解,在,持久编辑保持确认门,并为用户可见的更改提供测试和文档。

致谢

感谢以下测评级项目的启发:

License

发布在 MIT License 下。

这是一个独立的社区项目,不是 Cocos 官方产品。Ococos 和 Cocos Creator 为其相应拥有者的财产。


I need to make sure I didn't erroneously typing "Cocos " as "Cocos" in places: "Cocos Creator" — correct spelling is "Cocos Creator." The original "Coc os". I'll write "Cocos Creator".

Also "模块处理" etc. Fine.

Now let me finalize with exact text, ensuring table header "| Tools | Capabilities |". I'll use "工具" and "能力说明". The right column.

Actually the original header is > Tool|Capabilities`。I'll translate the text but keep the header exactly with the two columns. I can translate as "工具" / "能力" — the original "Capabilities" keeps tool. That's fine.

Now with this, the final output is set.

Also double-check the language switcher: "简体中文" — the original has "English | 简体中文". I keep it verbatim.

One more detail: The "Features" section's second sentence: "The server exposes 23 intent-oriented MCP tools" — "暴露" maybe "对外提供". Use "提供".

Also "Each tool groups related actions so clients receive a focused tool list while retaining broad editor coverage." -> "每个工具都会把相关操作组合在一起,让客户端获得一个聚焦的工具列表,同时保留对编辑器的广泛覆盖。"

Now, "Additional workflow features include..." - "此外,工作流特性还包括:感知会话状态的 Streamable HTTP、工具列表变更通知、Schema 验证输入、确认记录、支持回滚的批量操作和项目本地工具预设。" ("session-aware" -> 会话感知).

Now final answer.# Cocos MCP Community

English | 简体中文

一个由社区构建的 Model Context Protocol (MCP) 扩展,适用于 Cocos Creator 3.8+。连接兼容的 AI 客户端后,即可检查并操作 Cocos Creator 当前打开的项目。

该扩展在本地运行,监听在 127.0.0.1,对于持久性或结构性的变更,都必须明确确认。

当前版本:0.2.3。自动化测试套件已通过,主要的读取和隔离写入工作流已在 Cocos Creator 3.8.8 上验证。

功能

服务器对外提供 23 个以意图为导向的 MCP 工具。每个工具将相关操作组合在一起,使客户端获得一个集中的工具列表,同时保留编辑器的广泛覆盖能力。

工具

能力说明

project

读取项目信息和资源摘要;查询或更新项目配置

scene

检查当前场景与层级;打开、保存或另存为场景

node

发现、检查、创建、更新、复制、复制、剪切、剪切、粘贴、重置、重设父级或删除节点

component

列出、添加、移除、检查、编辑或重置组件;编辑数组和 Button 事件;应用文本样式

asset

列出并检查资源,读取内容安全的文本资源、导入、创建、保存、复制、移动、刷新、重新导入或删除资产

prefab

列出并检查 Prefab,查找引用,实例化关联或非关联副本,复制或删除资源,并恢复资产资源实例

snapshot

捕获和恢复层级快照;开始、提交或中止作用域事务

build

原子地检查验证节点树,或完整的 Canvas/Panel/Title/Button UI 场景

validation

检查层级结构和 UI 问题;验证引用页码,分析依赖、循环、缺失项和孤立候选

capture

捕获结构化的布局数据、Camera 渲染的 PNG、或裁剪的本地 Preview 画布 PNG

animation

创建、保存、批量生成、检查和增量编辑AnimationClip;附加并控制剪辑

viewport

读取设计分辨率和编辑框、编辑器状态、对焦点或对齐节点;配置 2D、网格、Gizmo、图标选项

editor

读取编辑器上下文、编辑器选项、脏状态、就绪状态、Creator 控制台条目、项目日志、Preview 错误

preview

检查 Preview 网络连接、启动支持的 Preview 目标,重新加载 Preview,停止 Game View、点击本地 Preview 按钮

ui

确保存在 Canvas,并创建模板、布局、对话框、列表、导航栏 Button、导航或设置声明

spine

为 sp.Skeleton 组件分配 Spine 数据,并列出、播放、排队或清除动画

font

列出项目字体;将项目字体或系统字体应用到 cc.Label

reference_image

列出 SpriteFrame,并从项目资源在场景中放置一张 reference image

environment

检查引擎与原生路径、设备、编辑器网络、编程环境与插件

knowledge

按主题检索内置的 cocos 工作流指南

server

读取本地服务状态及最近操作元数据

preferences

访问、恢复、恢复或重置项目本地工具选择的结果

client_config

为 Claude Desktop、Cursor、VS Code 或 Windsurf 生成客户端配置

其他工作流特性包括:检视会话感知的 URL 可流式 HTTP、工具列表变更通知、基于 Schema 的输入验证、确认门、支持错误的批量操作回滚,以及项目本地工具预设。

环境要求

  • Cocos Creator 3.8 或更高版本

  • Node.js 18 或更高版本

  • npm

  • 支持 Streamable HTTP 的 MCP 客户端

安装与使用

1. 安装扩展

将仓库克隆到 Cocos 项目的 extensions 目录,再安装依赖并构建:

cd /path/to/YourCocosProject/extensions
git clone <repository-url> cocos-mcp-community
cd cocos-mcp-community
npm ci
npm run build

在 Cocos Creator 中打开项目。如果编辑器已经打开,请重新加载扩展或重启编辑器。

2. 启动 MCP 服务器

打开 Extension → Cocos MCP Community 并选择 Start server。默认端点为:

http://127.0.0.1:3100/mcp

面板会显示当前端点和服务器状态。你也可以修改项目本地端口,或启用自动启动。

3. 连接 MCP 客户端

在客户端的 MCP 配置中新增一个 Streamable HTTP 服务器。通用的服务器配置项为:

{
  "type": "http",
  "url": "http://127.0.0.1:3100/mcp"
}

但客户端的其它配置各有不同。首次连接后,client_config 工具可生成 Claude Desktop、Cursor、VS Code 与 Windsurf 的完整配置。

更改客户端配置后请重启或重新连接 MCP 客户端。如果在 Cocos 面板中更改了服务器端口,请同时更新客户端 URL。

4. 验证连接

在 Cocos Creator 中保持目标项目和场景打开,然后让 AI 客户端执行一个只读操作,例如:

Summarize the current Cocos scene hierarchy.
List the assets under db://assets and report any missing references.
Check the current editor and Preview errors without changing the project.

如果客户端能返回项目或场景信息,即视为连接就绪;否则请参照故障排除。

5. 适使用编辑工作流

你可使用自然语言描述编辑器任务,例如:

Create a Canvas with a centered panel, a title, and a button in the current scene.
Set the selected Label font size to 32 and change its text to "Play".
Create an AnimationClip that moves the selected node from x=0 to x=300 in one second.

持久性和结构性变更需要确认。推荐的工作流程为:

  1. 让客户端检查当前状态,并说明它将进行的更改。

  2. 检查好目标场景、节点、资源和路径。

  3. 当客户端请求许可时确认该操作。

  4. 在临近 Cocos Creator 中检查结果,并且适时保存场景。

使用变更工具前请提交或备份重要内容。首次试用请使用一次性场景和临时资源。

工具管理

扩展面板包含两个标签页:

  • Server 控制端口、端口以及自动启动行为。

  • Tool management 提供单个工具的开关及 All 、Core workflow 、UI workflow 、Minimal 等预设。

减少暴露的工具集可减少发送给客户端的 MCP tool 结果。preferences recovery 工具始终可用。支持 tool-list change 设置的工具会以优秀的方式自动刷新;如果客户端不支持茶树该旧版本,请重连处理。

设置存储在项目一级的 library/cocos-mcp-community.settings.json 中。

故障排除

  • 客户端无法连接: 请确认 Cocos Editor 已打开、扩展已启用并显示服务器已启动;同时确认客户端使用的端口与面板一致。

  • 工具列表未更新错误: 修改 Tool management 设置后,重新连接 MCP 客户端。

  • 场景操作失败: 先打开目标位置,再尝试只读取场景摘要。

  • 编辑被拒绝: 验证目标 UUID 或 资源路径,并确认明确的写入操作请求。

  • 若端口出现冲突:在 Server 标签页 中选择一个介于 1024 和 65535 之间的端口,并相应更新客户端。

开发

npm install
npm run check
npm run build
npm run test:ci

命令

说明

npm run check

类型检查但不输出构建文件

npm run build

将扩展编译到 dist/

npm run test:regression

运行本地回归检测

npm run a test:smoke

运行回归及 MCP 传输/工具发现检查

npm run test:ci

构建并运行全套自动化测试套件

冒烟测试不会改动 Cocos 项目。而集成测试应使用一次性场景和临时资源。

项目结构

src/main.ts                 Extension lifecycle and panel messages
src/server/                 MCP transport, sessions, and tool registration
src/cocos/editor-bridge.ts  Cocos Editor integration
src/scene.ts                Scene-process operations
src/tools/                  Schema-validated MCP tools
src/panels/default/         Dockable extension panel
scripts/                    Regression and smoke tests

贡献

欢迎提交 Issue 和 Pull Request。请阅读 CONTRIBUTING.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
      -
    • 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.
      -