Cocos MCP

A Cocos Creator 3.8.x MCP bridge for code agents. The editor extension runs a local TCP socket server, and a Python MCP server (stdio) forwards tools over that socket. This mirrors the Blender MCP architecture.

Architecture

• Editor extension (TS): packages/cocos-mcp starts a TCP server inside Cocos Creator.

• MCP server (Python): python/src/cocos_mcp_server/server.py exposes tools over stdio and talks to the editor socket.

MCP Client (Claude Code / Cursor)
    ↕ stdio (MCP protocol)
Python MCP Server (cocos_mcp_server.py)
    ↕ TCP socket (JSON-RPC, port 8787)
Cocos Editor Extension (packages/cocos-mcp)
    ↕ Editor.Message / scene script APIs
Cocos Creator Engine

Related MCP server: Cocos Creator MCP Server

Install (Editor Side)

1. Copy packages/cocos-mcp into your Cocos project:

   • Preferred: extensions/cocos-mcp

   • Legacy: packages/cocos-mcp

2. Restart Cocos Creator and enable the extension in Extension Manager.

3. Optional: set port via env var before launching editor:

   • COCOS_MCP_PORT=8787

If you change TypeScript, rebuild:

npx tsc -p packages/cocos-mcp/tsconfig.json

Install (Python Side)

cd python && uv sync

Run MCP Server

cd python && uv run cocos-mcp-server --host 127.0.0.1 --port 8787

Claude Code Integration

Cocos MCP 完整支持 Claude Code —— Anthropic 官方的 CLI 编程工具。连接后，Claude Code 可以直接通过自然语言操控 Cocos Creator 编辑器：创建/删除节点、修改属性、管理资源、搭建 UI、配置物理和动画等。

快速添加（发布到 PyPI 后）

claude mcp add cocos-mcp-server uvx cocos-mcp-server

自动发现

项目根目录包含 .mcp.json 配置文件。在此目录下启动 Claude Code 时会自动发现并连接 MCP 服务器，无需额外配置。

cd /path/to/cocos-mcp
claude

手动配置

也可以将配置手动添加到 Claude Code 的设置中：

项目级别（.claude/settings.json）：

{
  "mcpServers": {
    "cocos-mcp": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/cocos-mcp/python", "cocos-mcp-server", "--port", "8787"]
    }
  }
}

全局级别（~/.claude/settings.json），适用于所有项目：

{
  "mcpServers": {
    "cocos-mcp": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/cocos-mcp/python", "cocos-mcp-server", "--port", "8787"]
    }
  }
}

使用流程

1. 启动 Cocos Creator 并打开包含 cocos-mcp 扩展的项目

2. 确认编辑器控制台输出 [cocos-mcp] TCP server listening on 127.0.0.1:8787

3. 在终端启动 Claude Code

4. Claude Code 会自动连接 MCP 服务器，5 个路由工具（ping/execute/scene/assets/editor）立即可用

使用示例

> 列出当前场景的所有节点

> 创建一个名为 Player 的节点，位置设为 (0, 1, 0)

> 给 Player 节点添加一个 RigidBody 和 BoxCollider

> 在场景中创建一个 Button，文字为"开始游戏"

> 把 Player 节点保存为 prefab 到 db://assets/prefabs/Player.prefab

> 查找项目中所有 prefab 资源

其他 MCP 客户端

Cursor、Windsurf 等支持 MCP 协议的工具也可以使用相同的配置格式接入。

Tools

当前是 5 个路由工具（旧版的 43 个平铺工具已收敛为 action 路由模型）：

• ping() – 连通性检查

• execute(scope, code, args) – 在 scene 或 main 作用域执行任意 JS

• scene(action, params) – 场景操作路由（节点 CRUD、组件、UI、动画、材质、物理等）

• assets(action, params) – 资产操作路由（查找、导入、移动、删除、依赖等）

• editor(action, params) – 编辑器操作路由（保存、打开场景、undo/redo、prefab 等）

新增 action 的方式：在 python/src/cocos_mcp_server/server.py 的映射表（SCENE_ACTIONS / ASSETS_ACTIONS / EDITOR_ACTIONS 等）登记，工具本身无需改动；可用 action 全集以映射表为准。

另有 3 个 MCP resources 提供参考文档：cocos://reference/scene、cocos://reference/assets、cocos://reference/editor。

Python 侧入口：python/src/cocos_mcp_server/server.py（编辑器扩展在 packages/cocos-mcp/）。

与 CelestialSphere 的同步

改完扩展（TS/Python）后，rsync 到宿主项目的扩展目录（对本目录的唯一 sanctioned 投放方式）：

rsync -av --delete --exclude .git \
  packages/cocos-mcp/ \
  /Users/wanghe/apps/engines/CelestialSphere/extensions/cocos-mcp/

Troubleshooting

"Failed to communicate with Cocos Creator"

• Make sure Cocos Creator is running and the project with the extension is open.

• Check that the extension is enabled in Extension Manager.

• Verify the port matches (default 8787). Check the editor console for [cocos-mcp] TCP server listening on 127.0.0.1:8787.

Port already in use

• Another instance may be using port 8787. Set a different port:

  COCOS_MCP_PORT=8788 # set before launching Cocos Creator
  python python/cocos_mcp_server.py --port 8788

Extension not loading

• Ensure package.json has "package_version": 2 and "editor": ">=3.8.0".

• The extension folder must be named cocos-mcp (matching the name field).

• Check the editor console for error messages.

Scene operations return "No active scene"

• Open a scene in the editor before calling scene tools.

Notes

• Asset operations map to common asset-db message names (e.g. query-assets). If your editor build differs, use assets_request with the exact method name.

• Scene modifications via MCP do not currently trigger the editor's undo system. Save your scene before making bulk changes.