🚀 Cocos Creator MCP Server插件
Cocos Creator MCP Server插件是一款全面的MCP(模型上下文协议)服务器插件,适用于Cocos Creator 3.8+版本。它允许AI助手通过标准化协议与Cocos Creator编辑器进行交互,支持一键安装和使用,无需复杂的环境配置。该插件已在Claude客户端Claude CLI和Cursor上进行了测试,理论上也能完美支持其他编辑器。
🚀 目前提供13大类共151种工具,实现了98%的编辑器控制!(预制体实例化存在已知的子节点恢复问题)
🚀 快速开始
链接导航
不同客户端配置示例
Claude cli配置
claude mcp add --transport http cocos-creator http://127.0.0.1:3000/mcp (使用您自己配置的端口号)
Claude客户端配置
{
"mcpServers": {
"cocos-creator": {
"type": "http",
"url": "http://127.0.0.1:3000/mcp"
}
}
}
Cursor或VS类MCP配置
{
"mcpServers": {
"cocos-creator": {
"url": "http://localhost:3000/mcp"
}
}
}
✨ 主要特性
🎯 场景操作
- 获取当前场景信息和完整的场景列表
- 通过路径打开场景并保存当前场景
- 创建具有自定义名称的新场景
- 获取包含组件信息的完整场景层次结构
🎮 节点操作
- 创建不同类型的节点(Node、2DNode、3DNode)
- 通过UUID获取节点信息并按名称模式查找节点
- 设置节点属性(位置、旋转、缩放、激活状态)
- 删除、移动和复制节点,支持完整的层次结构
🔧 组件操作
- 从节点添加/移除组件
- 获取节点的所有组件及其属性
- 动态设置组件属性
- 从资源路径附加脚本组件
- 按类别列出可用的组件类型
📦 预制体操作
- 列出项目中按文件夹组织的所有预制体
- 加载、实例化和创建预制体
- 更新现有预制体并还原预制体实例
- 获取包括依赖项在内的详细预制体信息
- ⚠️ 已知问题:由于Cocos Creator API的限制,预制体实例化可能无法正确恢复子节点。
🚀 项目控制
- 在预览模式下运行项目(浏览器/模拟器)
- 为不同平台(Web、移动、桌面)构建项目
- 获取项目信息和设置
- 刷新资源数据库并导入新资源
- 获取详细的资源信息
🔍 调试工具
- 获取经过过滤的编辑器控制台日志
- 清除控制台并在场景上下文中执行JavaScript
- 获取用于调试的详细节点树
- 性能统计和场景验证
- 获取编辑器和环境信息
⚙️ 附加功能
- 偏好设置管理:获取/设置编辑器偏好和全局设置
- 服务器控制:服务器信息、项目详细信息和编辑器控制
- 消息广播:监听和广播自定义消息
- 资源管理:创建、复制、移动、删除和查询资源
- 构建系统:项目构建和预览服务器控制
- 参考图像管理:在场景视图中添加、移除和管理参考图像
- 场景视图控制:控制小控件工具、坐标系和视图模式
- 高级场景操作:撤销/重做、快照和高级节点操作
📦 安装指南
1. 复制插件文件
将整个 cocos-mcp-server
文件夹复制到您的Cocos Creator项目的 extensions
目录中:
YourProject/
├── assets/
├── extensions/
│ └── cocos-mcp-server/ <- 将插件放置在此处
│ ├── source/
│ ├── dist/
│ ├── package.json
│ └── ...
├── settings/
└── ...
2. 安装依赖项
cd extensions/cocos-mcp-server
npm install
3. 构建插件
npm run build
4. 启用插件
- 重启Cocos Creator或刷新扩展。
- 插件将出现在扩展菜单中。
- 点击
扩展 > Cocos MCP Server
打开控制面板。
💻 使用示例
基础用法
创建新的精灵节点
{
"tool": "node_create_node",
"arguments": {
"name": "MySprite",
"nodeType": "2DNode",
"parentUuid": "parent-node-uuid"
}
}
添加精灵组件
{
"tool": "component_add_component",
"arguments": {
"nodeUuid": "node-uuid",
"componentType": "cc.Sprite"
}
}
实例化预制体
{
"tool": "prefab_instantiate_prefab",
"arguments": {
"prefabPath": "db://assets/prefabs/Enemy.prefab",
"position": { "x": 100, "y": 200, "z": 0 }
}
}
⚠️ 重要提示
由于Cocos Creator API的限制,带有子节点的复杂预制体可能无法正确实例化,实例化的预制体中可能会缺少子节点。
在浏览器中运行项目
{
"tool": "project_run_project",
"arguments": {
"platform": "browser"
}
}
📚 详细文档
工具配置
设置存储在 YourProject/settings/mcp-server.json
中:
{
"port": 3000,
"autoStart": false,
"enableDebugLog": true,
"allowedOrigins": ["*"],
"maxConnections": 10
}
图标设置
要为插件面板添加图标:
- 创建一个PNG图标文件(推荐尺寸:32x32或64x64)。
- 将其放置在
static/
目录中:static/icon.png
。
- 图标路径已在
package.json
中配置。
🔧 技术细节
项目结构
cocos-mcp-server/
├── source/ # TypeScript源文件
│ ├── main.ts # 插件入口点
│ ├── mcp-server.ts # MCP服务器实现
│ ├── settings.ts # 设置管理
│ ├── types/ # TypeScript类型定义
│ ├── tools/ # 工具实现
│ │ ├── scene-tools.ts
│ │ ├── node-tools.ts
│ │ ├── component-tools.ts
│ │ ├── prefab-tools.ts
│ │ ├── project-tools.ts
│ │ ├── debug-tools.ts
│ │ ├── preferences-tools.ts
│ │ ├── server-tools.ts
│ │ ├── broadcast-tools.ts
│ │ ├── scene-advanced-tools.ts
│ │ ├── scene-view-tools.ts
│ │ ├── reference-image-tools.ts
│ │ └── asset-advanced-tools.ts
│ ├── panels/ # UI面板实现
│ └── test/ # 测试文件
├── dist/ # 编译后的JavaScript输出
├── static/ # 静态资产(图标等)
├── i18n/ # 国际化文件
├── package.json # 插件配置
└── tsconfig.json # TypeScript配置
从源代码构建
npm install
npm run watch
npm run build
添加新工具
- 在
source/tools/
中创建一个新的工具类。
- 实现
ToolExecutor
接口。
- 将工具添加到
mcp-server.ts
的初始化中。
- 工具将通过MCP协议自动公开。
TypeScript支持
该插件完全用TypeScript编写,具有以下特点:
- 启用严格的类型检查
- 为所有API提供全面的类型定义
- 开发时支持智能感知
- 自动编译为JavaScript
运行测试
node comprehensive-test.js
./test-all-features.sh
node test-mcp-server.js
故障排除
常见问题
- 服务器无法启动:检查端口可用性和防火墙设置。
- 工具无法正常工作:确保场景已加载且UUID有效。
- 构建错误:运行
npm run build
检查TypeScript错误。
- 连接问题:验证HTTP URL和服务器状态。
调试模式
在插件面板中启用调试日志以获取详细的操作日志。
使用调试工具
{
"tool": "debug_get_console_logs",
"arguments": {"limit": 50, "filter": "error"}
}
{
"tool": "debug_validate_scene",
"arguments": {"checkMissingAssets": true}
}
系统要求
- Cocos Creator 3.8.6或更高版本
- Node.js(随Cocos Creator捆绑)
- TypeScript(作为开发依赖项安装)
架构说明
此插件使用简化的MCP协议实现,与Cocos Creator的CommonJS环境兼容。HTTP服务器为AI助手提供了一个JSON-RPC接口,用于与编辑器进行交互。
协议支持
- HTTP连接:
http://localhost:3000/mcp
(端口可配置)
- JSON-RPC 2.0:标准请求/响应格式
- 工具发现:
tools/list
方法返回可用工具
- 工具执行:
tools/call
方法执行特定工具
📄 许可证
本插件用于Cocos Creator项目,源代码未加密且打包在一起,可用于学习和交流。支持您进行二次开发和优化,但本项目的任何代码或其衍生代码不得用于任何商业目的或转售。如需商业使用,请与我联系。