Cocos MCP Server

适用于 Cocos Creator 3.8.x 的 AI MCP (Model Context Protocol) 服务器插件，让 AI 助手（Claude、Cursor 等）能够直接控制 Cocos Creator 编辑器。

An AI MCP (Model Context Protocol) server plugin for Cocos Creator 3.8.x, enabling AI assistants (Claude, Cursor, etc.) to directly control the Cocos Creator editor.

功能特性 / Features

• MCP 协议 / MCP Protocol：基于 JSON-RPC 2.0 的标准 MCP 协议，通过 HTTP 传输 / Standard JSON-RPC 2.0 over HTTP transport

• 130+ 工具 / 130+ Tools：覆盖场景、节点、组件、预制体、资源、项目等全方位编辑器操作 / Full coverage of scene, node, component, prefab, asset, and project operations

• Vue 3 控制面板 / Vue 3 Control Panel：内置服务器控制和工具管理界面 / Built-in server control and tool management UI

• 工具配置管理 / Tool Configuration：按需启用/禁用工具，保存自定义配置 / Enable/disable tools on demand and save custom configurations

• 自动启动 / Auto-start：可配置插件加载时自动启动服务器 / Optionally start the server automatically when the extension loads

• 双语支持 / Bilingual UI：中文/英文界面 / English and Chinese interface

兼容性 / Compatibility

安装方法 / Installation

方式一：项目级插件 / Option 1: Project-level Extension

将插件目录复制到 Cocos Creator 项目的 extensions 目录下：

Copy the plugin folder into the extensions directory of your Cocos Creator project:

{your-project}/
└── extensions/
    └── cocos-mcp-server/

方式二：全局插件 / Option 2: Global Extension

将插件目录复制到全局插件目录：

Copy the plugin folder to the global extensions directory:

~/.CocosCreator/extensions/cocos-mcp-server/

启用插件 / Enable the Extension

1. 打开 Cocos Creator 3.8.x / Open Cocos Creator 3.8.x

2. 菜单栏 → 扩展 → 扩展管理器 / Go to Extension → Extension Manager

3. 在 项目 或 全局 标签页找到 cocos-mcp-server / Find cocos-mcp-server under the Project or Global tab

4. 点击启用 / Click Enable

开发构建 / Development Build

# 安装依赖 / Install dependencies
npm install

# 编译 TypeScript / Compile TypeScript
npm run build

# 开发模式（文件监听）/ Development mode (file watching)
npm run watch

编译输出位于 dist/ 目录。/ Compiled output is placed in the dist/ directory.

使用方法 / Usage

1. 启动服务器 / Start the Server

插件启用后，通过菜单 扩展 → Cocos MCP Server 打开控制面板，点击"启动服务器"。

After enabling the extension, open the control panel via Extension → Cocos MCP Server, then click Start Server.

默认服务器地址 / Default server address：http://127.0.0.1:3000/mcp

2. 连接 AI 客户端 / Connect an AI Client

Claude Code:

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

Claude Desktop (claude_desktop_config.json):

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

Cursor / VS Code: 在 MCP 设置中添加 HTTP 类型服务器，URL 填写 http://127.0.0.1:3000/mcp。

Add an HTTP-type MCP server in your MCP settings and set the URL to http://127.0.0.1:3000/mcp.

工具列表 / Tool Reference

场景工具 / Scene Tools (8)

节点工具 / Node Tools (11)

组件工具 / Component Tools

预制体工具 / Prefab Tools

资源工具 / Asset Tools

项目工具 / Project Tools

调试工具 / Debug Tools (10)

场景视图工具 / Scene View Tools (18)

操控场景视图中的 Gizmo 工具、坐标系、视图模式、网格显示等。

Control gizmo tools, coordinate systems, view modes, grid display, and other scene viewport settings.

高级场景工具 / Advanced Scene Tools (18)

撤销录制、节点复制粘贴剪切、场景快照、软重载等高级操作。

Undo recording, node copy/paste/cut, scene snapshots, soft reload, and other advanced operations.

参考图工具 / Reference Image Tools

场景视图中参考图片的添加、移除、变换操作。

Add, remove, and transform reference images in the scene viewport.

高级资源工具 / Advanced Asset Tools

批量资源操作、资源依赖分析等。

Batch asset operations and asset dependency analysis.

广播工具 / Broadcast Tools (5)

向编辑器发送自定义事件广播。

Send custom event broadcasts to the editor.

服务器工具 / Server Tools (6)

查询服务器状态、连接信息、工具列表等。

Query server status, connection information, and the active tool list.

验证工具 / Validation Tools (3)

场景完整性验证、资源依赖验证、MCP 响应格式验证。

Scene integrity validation, asset dependency validation, and MCP response format validation.

服务器设置 / Server Settings

工具管理 / Tool Management

控制面板的"工具管理"标签页支持：

The Tool Management tab in the control panel supports:

• 按类别管理 / Per-category control：每个工具类别独立控制 / Enable or disable tools by category

• 批量操作 / Bulk operations：全选/全不选 / Select all / deselect all

• 保存配置 / Persistent config：将工具启用状态持久化 / Save the enabled/disabled state across sessions

禁用不需要的工具可减小 AI 的工具上下文，提高响应效率。

Disabling unused tools reduces the AI's tool context size and can improve response efficiency.

项目结构 / Project Structure

cocos-mcp-server/
├── package.json              # 插件清单 / Extension manifest
├── tsconfig.json             # TypeScript 配置 / TypeScript configuration
├── base.tsconfig.json        # 基础 TS 配置 / Base TypeScript configuration
├── i18n/
│   ├── en.js                 # 英文本地化 / English localization
│   └── zh.js                 # 中文本地化 / Chinese localization
├── static/
│   ├── icon.png              # 插件图标 / Extension icon
│   ├── style/default/        # 面板样式 / Panel stylesheet
│   └── template/             # 面板 HTML 模板 / Panel HTML templates
├── source/
│   ├── main.ts               # 插件入口 / Extension entry point
│   ├── mcp-server.ts         # HTTP MCP 服务器核心 / HTTP MCP server core
│   ├── scene.ts              # 场景脚本（引擎 API）/ Scene script (engine API access)
│   ├── settings.ts           # 设置持久化 / Settings persistence
│   ├── types/index.ts        # TypeScript 类型定义 / TypeScript type definitions
│   ├── panels/default/       # Vue 3 控制面板 / Vue 3 control panel
│   └── tools/                # 工具模块（14个）/ Tool modules (14 categories)
└── dist/                     # 编译输出 / Compiled JavaScript output

架构说明 / Architecture

AI 客户端 / AI Client (Claude / Cursor)
       │  HTTP JSON-RPC 2.0
       ▼
MCP HTTP 服务器 / MCP HTTP Server (localhost:3000)
       │  Editor.Message IPC
       ▼
Cocos Creator 编辑器进程 / Editor Process
       │  execute-scene-script
       ▼
场景脚本 / Scene Script (engine API: cc.*)

• 主进程 / Main process (main.ts)：管理服务器生命周期、插件消息处理 / Manages the server lifecycle and handles extension messages

• MCP 服务器 / MCP server (mcp-server.ts)：实现 JSON-RPC 2.0 协议，路由工具调用 / Implements the JSON-RPC 2.0 protocol and routes tool calls

• 工具模块 / Tool modules (tools/*.ts)：封装具体的 Editor.Message 调用 / Wrap specific Editor.Message calls for each operation

• 场景脚本 / Scene script (scene.ts)：在引擎上下文中运行，直接访问 cc API / Runs in the engine context with direct access to cc APIs

• 控制面板 / Control panel (panels/default/index.ts)：Vue 3 UI，通过 IPC 与主进程通信 / Vue 3 UI that communicates with the main process via IPC

常见问题 / Troubleshooting

Q: 服务器启动失败，提示端口被占用 / The server fails to start with a "port in use" error.

在控制面板修改端口号（默认 3000），保存设置后重新启动。

Change the port number in the control panel (default is 3000) and restart the server.

Q: AI 工具调用失败，返回 "Scene not ready" / AI tool calls fail with "Scene not ready".

确保 Cocos Creator 中已打开一个场景。场景脚本需要活跃的场景上下文。

Make sure a scene is open in Cocos Creator. The scene script requires an active scene context to operate.

Q: 插件在扩展管理器中不显示 / The extension does not appear in the Extension Manager.

检查插件目录名是否与 package.json 中的 name 字段一致（cocos-mcp-server）。

Verify that the plugin folder name matches the name field in package.json (cocos-mcp-server).

Q: 修改源码后如何更新 / How do I apply source code changes?

运行 npm run build，然后在扩展管理器中禁用再重新启用插件。

Run npm run build, then disable and re-enable the extension in the Extension Manager.

许可证 / License

MIT