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 工具。每个工具都将相关操作分组，使客户端获得聚焦的工具列表，同时保留编辑器的广泛覆盖能力。

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

冒烟测试套件不会修改任何 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 来了解,在，持久编辑保持确认门，并为用户可见的更改提供测试和文档。

致谢

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

• caravaglory/cocos-mcp-server

• DaxianLee/cocos-mcp-server

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 工具。每个工具将相关操作组合在一起，使客户端获得一个集中的工具列表，同时保留编辑器的广泛覆盖能力。

其他工作流特性包括：检视会话感知的 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

冒烟测试不会改动 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，为持续修改保留确认入口，并为面向用户的功能附上测试和文档。

致谢

感谢以下开源项目提供的参考与灵感：

• acy/cocos-mcp-server

• DaxianLee/cocos-mcp-server

许可证

以 MIT License 协议发布。

这是一个独立的社区项目，并非 Cocos 官方产品。Cocos 及 Cocos Creator 均为其各自所有者的商标。