Cocos Creator Local MCP

English | 简体中文

cocos-creator-local-mcp is an MCP server for local Cocos Creator automation. It gives coding agents a practical tool surface for creating Cocos Creator 3.8 projects, installing a project-local editor bridge, assembling scenes, saving editor state, and building local WeChat Mini Game packages.

This project is intentionally focused on local project automation, not AI asset generation. Pair it with an asset pipeline MCP when your workflow needs generated sprites, audio, UI packs, or tilesets.

Why This Exists

Coding agents can write TypeScript, but Cocos games are not finished by code alone. A playable local prototype also needs scene files, node hierarchies, serialized component references, editor imports, build configuration, and platform output checks.

This MCP closes that local loop:

create project -> create scene -> generate scripts -> open editor
  -> apply scene blueprint -> save scene -> write build config
  -> build wechatgame -> inspect output

It is designed for agent-driven development on a developer machine where Cocos Creator is installed locally.

Related MCP server: mcp-bridge

Highlights

• Local-first Cocos Creator 3.8 workflow with no cloud service dependency.

• Project creation from Cocos Creator built-in templates.

• Project-local editor bridge extension for scene inspection and mutation.

• Generated mini-game starter scripts and scene blueprints.

• Scene opening, node creation, component attachment, property assignment, and save operations through the bridge.

• High-level sprite placement helpers for generated Cocos assets.

• Repeatable wechatgame build configuration and command-line build execution.

• Output checks for required WeChat Mini Game files and package-size warnings.

• Clean responsibility boundary: this MCP automates Cocos locally; asset generation belongs in a separate asset MCP.

Quick Links

• Install

• MCP Client Config

• Tools

• From Zero To Local WeChat Build

• LLM Install Prompt

• Architecture

• Uninstall

Requirements

• Node.js 20 or newer.

• macOS for the default paths currently documented here.

• Cocos Creator 3.8.8 installed locally, or pass creatorPath to tools.

• WeChat DevTools is optional unless you want to open/debug the built package in the simulator.

Default Cocos Creator executable path on macOS:

/Applications/Cocos/Creator/3.8.8/CocosCreator.app/Contents/MacOS/CocosCreator

Default WeChat DevTools CLI path on macOS:

/Applications/wechatwebdevtools.app/Contents/MacOS/cli

Install

git clone https://github.com/lightblink/cocos-creator-local-mcp.git
cd cocos-creator-local-mcp
npm install
npm run build

Run locally during development:

npm run dev

Use the built server:

node dist/index.js

Validate the project:

npm run check

MCP Client Config

Example for MCP clients that launch stdio servers:

{
  "mcpServers": {
    "cocos-creator-local": {
      "command": "node",
      "args": [
        "/absolute/path/to/cocos-creator-local-mcp/dist/index.js"
      ],
      "startup_timeout_sec": 120
    }
  }
}

If you also use an asset generation MCP, keep it as a separate server:

{
  "mcpServers": {
    "cocos-creator-local": {
      "command": "node",
      "args": [
        "/absolute/path/to/cocos-creator-local-mcp/dist/index.js"
      ]
    },
    "cocos-asset-forge": {
      "command": "node",
      "args": [
        "/absolute/path/to/cocos-asset-forge-mcp/dist/index.js",
        "--config",
        "/absolute/path/to/cocos-asset-forge-mcp/examples/config.example.json"
      ]
    }
  }
}

Tools

Generated Assets To Scene

When paired with an asset generation MCP, write generated PNGs under the Cocos project assets/ folder, wait for Cocos AssetDB import, then place them with cocos_local_place_sprite_assets.

Example sprite placement payload:

{
  "projectRoot": "/absolute/path/to/my-cocos-project",
  "openScene": true,
  "sprites": [
    {
      "assetPath": "assets/generated/background.png",
      "nodePath": "Scene/Canvas/GameRoot/Background",
      "position": { "x": 0, "y": 0, "z": -10 },
      "scale": { "x": 1, "y": 1, "z": 1 }
    },
    {
      "assetPath": "assets/generated/player.png",
      "nodePath": "Scene/Canvas/GameRoot/Player",
      "position": { "x": 0, "y": -120, "z": 0 },
      "scale": { "x": 1, "y": 1, "z": 1 }
    }
  ]
}

assetPath accepts db://assets/..., assets/..., an absolute project path, or a SpriteFrame UUID. The tool resolves AssetDB info and prefers SpriteFrame sub-assets when assigning Sprite.spriteFrame.

From Zero To Local WeChat Build

1. Call cocos_local_get_environment to confirm local paths.

2. Call cocos_local_create_project with a target projectRoot.

3. Call cocos_local_open_project with waitForBridge: true.

4. Call cocos_local_apply_scene_blueprint to create and wire the starter scene.

5. Call cocos_local_create_wechat_build_config with startScenePath: "assets/scenes/Main.scene".

6. Call cocos_local_build_wechatgame.

7. Call cocos_local_check_wechat_build_output.

Cocos Creator returns exit code 36 for a successful command-line build.

Editor Bridge

The bridge is installed into the target Cocos project as a project-local extension:

extensions/codex-editor-bridge/

It exposes a localhost HTTP API while the project is open in Cocos Creator. The MCP uses that API to inspect and edit the active scene. The extension is local to the project being automated and should not be shipped with your game runtime.

Local Safety Boundary

This server is for local development and packaging only. It does not:

• upload WeChat Mini Game builds

• submit review or release candidates

• manage production app credentials

• change payment, ads, login, or backend configuration

• generate art or audio assets

Use placeholder WeChat appids only for pure local gameplay checks. Use a real appid before testing platform APIs.

Development

npm install
npm run typecheck
npm test
npm run build

The unit tests verify the editor bridge scaffold and generated mini-game skeleton. A full local smoke test also requires Cocos Creator 3.8.8 on the host machine.

Trademark Notice

Cocos Creator and WeChat are trademarks of their respective owners. This project is an unofficial local automation tool and is not affiliated with or endorsed by Cocos or Tencent.