Cocos4 MCP Server AI

An AI-native scaffold and enhanced Model Context Protocol (MCP) server for building games with Cocos4 using AI coding agents such as Codex, Claude Code, and other MCP-compatible clients.

Cocos4 is a fully open-source (MIT), headless-first game engine — a rare fit for AI agents, since the entire editing pipeline can run from a CLI without a GUI. Its CLI (cocos-cli) already ships a built-in MCP server exposing ~50 low-level tools for scene, node, component, prefab, asset, and build operations. This project builds on top of that, rather than duplicating it:

• Proxies all native Cocos4 MCP tools transparently, so this project stays in sync as cocos-cli evolves — no hand-maintained tool schemas to drift out of date.

• Adds high-level scaffolding tools that the native server doesn't provide: project bootstrapping, TypeScript component/manager code generation, and ready-to-use gameplay templates (platformer, top-down shooter, match-3, endless runner, turn-based RPG, UI app).

• Ships a CLI (cocos4-ai) to bootstrap AI-ready projects with MCP client config already wired up.

Why this exists

Cocos4 went fully open source in January 2026 (MIT license, all commercial clauses removed). Its CLI is still in early alpha, and the native MCP server is powerful but low-level — an AI agent has to know exact tool names, path conventions (Canvas/Node1/cc.Sprite vs Canvas/Node1), and multi-step sequences (create scene → open scene → create node → add component → set property → save scene) to get anything done.

This project is the missing layer between "raw engine primitives" and "an AI agent that can build a whole game from a prompt": project templates, codegen, and a single unified MCP endpoint that Codex (or any MCP client) can point at.

Related MCP server: Cocos MCP Server

Architecture

┌─────────────────────┐
│   Codex / Claude /   │
│   any MCP client     │
└──────────┬───────────┘
           │ stdio (MCP)
┌──────────▼───────────┐
│   cocos4-ai server    │  ← this project
│  ┌─────────────────┐  │
│  │ High-level tools │  │  project init, codegen, templates
│  └─────────────────┘  │
│  ┌─────────────────┐  │
│  │  Native proxy    │──┼──► streamable-HTTP (MCP) ──► cocos start-mcp-server
│  └─────────────────┘  │                                (50 native tools:
└───────────────────────┘                                 scene-*, assets-*,
                                                            builder-*, file-*,
                                                            system-*)

The server uses the MCP SDK's low-level Server class (not the high-level McpServer helper) so it can merge tools/list responses from two sources — the native Cocos4 CLI MCP server and this project's own tools — and route tools/call requests to whichever one owns the tool name.

Requirements

• Node.js ≥ 22

• Cocos4 CLI installed and available on PATH as cocos

Installation

git clone git@github.com:usernema/cocos4-mcp-server-AI.git
cd cocos4-mcp-server-AI
npm install
npm run build
npm link   # makes `cocos4-ai` available globally

Usage

1. Bootstrap a new project

cocos4-ai init my-game --type 3d

This creates the Cocos4 project via cocos create and writes an MCP client config (.mcp/config.json) so any MCP-compatible agent can connect immediately.

2. Point your AI agent at the server

For Codex, Claude Code, or any MCP client, add to its MCP config:

{
  "mcpServers": {
    "cocos4-ai": {
      "command": "cocos4-ai",
      "args": ["serve", "--project", "./my-game"]
    }
  }
}

3. Let the agent build the game

Once connected, the agent has access to:

• cocos4_verify_installation, cocos4_create_project, cocos4_connect, cocos4_run_cli_command — environment and project lifecycle

• cocos4_list_templates, cocos4_apply_template — bootstrap common gameplay patterns

• cocos4_generate_component, cocos4_generate_manager — generate typed TypeScript scripts

• ~50 native tools proxied from cocos start-mcp-server, once cocos4_connect is called:

  • scene-* — create/open/save/close scenes, query and mutate the node tree

  • scene-create-node-by-type, scene-update-node, scene-delete-node

  • scene-add-component, scene-set-component-property, scene-query-component

  • create-prefab-from-node, apply-prefab-changes, revert-prefab

  • assets-* — asset CRUD, metadata, import/reimport

  • builder-build, builder-run, builder-make — compile and launch builds

  • file-insert-text, file-replace-text, file-query-text — precise script editing

  • system-query-logs — read CLI logs for debugging

The agent should always call a *-query-* tool before mutating anything, to fetch exact node paths/UUIDs rather than guessing them (the native server enforces this — see scene-query-node vs scene-query-component distinctions in each tool's description).

CLI reference

cocos4-ai check                          # verify cocos-cli is installed
cocos4-ai init <name> [--type 2d|3d]     # bootstrap a new AI-ready project
cocos4-ai serve --project <path>         # start the MCP server (stdio transport)
  [--native-port <port>]                 # port for the native Cocos MCP server (default 9527)
  [--no-auto-start]                      # don't auto-connect to a native server on boot
  [--debug]                              # verbose logging to stderr

Available templates

Development

npm run dev     # tsc --watch
npm run build   # compile TypeScript
npm test        # run tests (vitest)

Project status

This is an early-stage project built to accompany an application to OpenAI's Codex for Open Source program. Cocos4 itself is in active development (CLI at 0.0.1-alpha.x as of writing) — expect native tool names/schemas to evolve, which is exactly why this project proxies rather than duplicates them.

Contributions and issue reports welcome.

License

MIT