MCPInstall

cocos-creator-mcp-server

by reason-machinesAI & Agents

MCP server plugin for Cocos Creator 3.8+ that enables AI assistants to control the editor through 50 powerful tools for scenes, nodes, components, prefabs, and assets.

Installs
221
Last 24h
—
Trending rank
—
Security
Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/reason-machines/mcp-skills --skill cocos-creator-mcp-server
  1. 01

    Install

    Run the command in your project. The CLI asks which agents to install for.

  2. 02

    Describe the task

    Ask your agent for something this skill covers. It loads cocos-creator-mcp-server automatically when relevant.

  3. 03

    Review the result

    The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

Cocos Creator MCP Server Skill

Skill by ara.so — MCP Skills collection.

A comprehensive MCP (Model Context Protocol) server plugin for Cocos Creator 3.8+ that enables AI assistants to interact with the Cocos Creator editor through a standardized protocol. Provides 50 powerful tools covering 99% of editor operations including scenes, nodes, components, prefabs, assets, project management, debugging, and preferences.

Installation

Prerequisites

  • Cocos Creator 3.8.6 or higher
  • MCP-compatible client (Claude Desktop, Claude CLI, Cursor, etc.)

Plugin Installation

  1. From Cocos Store (Recommended):

  2. Manual Installation:

    # Clone the repository
git clone https://github.com/DaxianLee/cocos-mcp-server.git

# Install in Cocos Creator extensions folder
# Windows: %USERPROFILE%/.CocosCreator/extensions/
# macOS: ~/.CocosCreator/extensions/
# Copy the plugin folder to the extensions directory

  3. Enable in Cocos Creator:

    • Open Cocos Creator
    • Go to Extensions → Extension Manager
    • Find "Cocos Creator MCP Server" and enable it
    • Configure server port (default: 3000) in the MCP panel

Client Configuration

Claude Desktop (claude_desktop_config.json):

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

Claude CLI:

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

Cursor (.cursor/mcp.json or settings):

{
  "mcpServers": {
    "cocos-creator": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

Core Concepts

Action-Based Tool System

All 50 tools follow a unified "action + parameters" pattern:

{
  "tool": "category_operation",
  "arguments": {
    "action": "specific_action",
    // ... action-specific parameters
  }
}

This design reduces token consumption by ~50% and increases AI call success rates.

Tool Categories

  • scene_* - Scene management and hierarchy
  • node_* - Node lifecycle, transforms, and hierarchy
  • component_* - Component management and scripting
  • prefab_* - Prefab browsing, creation, and instantiation
  • asset_* - Asset management and analysis
  • project_* - Project control and build system
  • debug_* - Console, logs, and system debugging
  • preferences_* - Editor preferences
  • server_* - Server information
  • broadcast_* - Message broadcasting

Key Tools & Usage

Scene Management

Get Current Scene

// Tool: scene_management
{
  "action": "get_current_scene"
}
// Returns: { uuid: string, name: string, path: string }

Open Scene

{
  "action": "open_scene",
  "sceneUuid": "scene-uuid-here"
}

Create New Scene

{
  "action": "create_scene",
  "name": "MyNewScene",
  "savePath": "db://assets/scenes/"
}

Save Current Scene

{
  "action": "save_scene"
}

Node Operations

Create Node

// Tool: node_lifecycle
{
  "action": "create",
  "name": "PlayerNode",
  "parentUuid": "parent-node-uuid",  // Optional, defaults to scene root
  "nodeType": "2DNode",  // or "3DNode"
  "components": [  // Optional pre-installed components
    {
      "type": "cc.Sprite",
      "properties": {
        "spriteFrame": "texture-uuid"
      }
    }
  ]
}

Query Nodes

// Tool: node_query
{
  "action": "find_by_name",
  "name": "Player",
  "exactMatch": false  // Use pattern matching
}

// Or find all nodes
{
  "action": "find_all",
  "includeComponents": true
}

Delete Node

// Tool: node_lifecycle
{
  "action": "delete",
  "uuid": "node-uuid-to-delete"
}

Transform Node

// Tool: node_transform
{
  "action": "set_property",
  "uuid": "node-uuid",
  "property": "position",
  "value": { "x": 100, "y": 200, "z": 0 }
}

// Set rotation
{
  "action": "set_property",
  "uuid": "node-uuid",
  "property": "rotation",
  "value": { "x": 0, "y": 0, "z": 45 }  // Euler angles
}

// Set scale
{
  "action": "set_property",
  "uuid": "node-uuid",
  "property": "scale",
  "value": { "x": 2, "y": 2, "z": 1 }
}

Move Node in Hierarchy

// Tool: node_hierarchy
{
  "action": "move",
  "uuid": "node-uuid",
  "newParentUuid": "new-parent-uuid",
  "siblingIndex": 0  // Optional position among siblings
}

Component Management

Add Engine Component

// Tool: component_manage
{
  "action": "add",
  "nodeUuid": "node-uuid",
  "componentType": "cc.Sprite",
  "properties": {
    "spriteFrame": "texture-uuid",
    "sizeMode": 0
  }
}

// Common component types:
// cc.Sprite, cc.Label, cc.Button, cc.RichText,
// cc.UITransform, cc.Canvas, cc.Widget,
// cc.BoxCollider2D, cc.RigidBody2D, etc.

Attach Custom Script

// Tool: component_script
{
  "action": "add_script",
  "nodeUuid": "node-uuid",
  "scriptName": "PlayerController",  // Script file name without .ts
  "properties": {
    "speed": 100,
    "jumpForce": 500
  }
}

Get Component Information

// Tool: component_query
{
  "action": "get_components",
  "nodeUuid": "node-uuid"
}
// Returns array with type (cid) and properties for each component

Remove Component (IMPORTANT)

// Tool: component_manage
// MUST use component's cid (type field), NOT script name!
// First, get component info:
{
  "action": "get_components",
  "nodeUuid": "node-uuid"
}
// Returns: [{ type: "comp.PlayerController!1234abcd", ... }]

// Then remove using exact type (cid):
{
  "action": "remove",
  "nodeUuid": "node-uuid",
  "componentType": "comp.PlayerController!1234abcd"  // Use exact cid
}

Set Component Properties

// Tool: set_component_property
{
  "nodeUuid": "node-uuid",
  "componentType": "cc.Sprite",
  "properties": {
    "color": { "r": 255, "g": 0, "b": 0, "a": 255 }
  }
}

// For custom scripts, use full cid from get_components
{
  "nodeUuid": "node-uuid",
  "componentType": "comp.PlayerController!1234abcd",
  "properties": {
    "health": 100,
    "maxSpeed": 200
  }
}

Prefab Operations

List Prefabs

// Tool: prefab_browse
{
  "action": "list",
  "folderPath": "db://assets/prefabs/"  // Optional
}

Create Prefab from Node

// Tool: prefab_lifecycle
{
  "action": "create",
  "nodeUuid": "source-node-uuid",
  "savePath": "db://assets/prefabs/MyPrefab.prefab"
}

Instantiate Prefab

// Tool: prefab_instance
{
  "action": "instantiate",
  "prefabUuid": "prefab-uuid",
  "parentUuid": "parent-node-uuid",  // Optional
  "position": { "x": 0, "y": 0, "z": 0 }  // Optional
}

Apply Instance Changes to Prefab

// Tool: prefab_instance
{
  "action": "apply",
  "nodeUuid": "prefab-instance-uuid"
}

Revert Instance to Original

// Tool: prefab_instance
{
  "action": "revert",
  "nodeUuid": "prefab-instance-uuid"
}

Asset Management

Import Assets

// Tool: asset_manage
{
  "action": "import",
  "paths": [
    "/path/to/texture.png",
    "/path/to/audio.mp3"
  ]
}

Query Assets by Type

// Tool: asset_query
{
  "action": "query_by_type",
  "type": "cc.Texture2D",  // cc.Texture2D, cc.SpriteFrame, cc.Prefab, cc.AudioClip, etc.
  "folder": "db://assets/textures/"  // Optional
}

Get Asset Dependencies

// Tool: asset_analyze
{
  "action": "get_dependencies",
  "uuid": "asset-uuid"
}

Delete Asset

// Tool: asset_operations
{
  "action": "delete",
  "uuid": "asset-uuid"
}

Project Control

Run Project

// Tool: project_manage
{
  "action": "run",
  "preview": true  // false for simulator
}

Build Project

// Tool: project_build_system
{
  "action": "build",
  "platform": "web-mobile",  // web-mobile, android, ios, windows, mac
  "buildPath": "/path/to/build/output"
}

Get Project Info

// Tool: project_manage
{
  "action": "get_info"
}
// Returns project name, version, path, settings

Debugging

Get Console Logs

// Tool: debug_console
{
  "action": "get_logs",
  "filter": "error",  // Optional: log, warn, error
  "limit": 50  // Optional
}

Clear Console

// Tool: debug_console
{
  "action": "clear"
}

Search Log Files

// Tool: debug_logs
{
  "action": "search",
  "pattern": "Error:",
  "maxLines": 100
}

Common Patterns

Creating a Complete Game Object

// 1. Create node
const createNode = {
  tool: "node_lifecycle",
  arguments: {
    action: "create",
    name: "Player",
    nodeType: "2DNode"
  }
};
// Response includes: { uuid: "player-node-uuid" }

// 2. Add sprite component
const addSprite = {
  tool: "component_manage",
  arguments: {
    action: "add",
    nodeUuid: "player-node-uuid",
    componentType: "cc.Sprite",
    properties: {
      spriteFrame: "player-texture-uuid"
    }
  }
};

// 3. Attach script
const addScript = {
  tool: "component_script",
  arguments: {
    action: "add_script",
    nodeUuid: "player-node-uuid",
    scriptName: "PlayerController",
    properties: {
      speed: 300,
      health: 100
    }
  }
};

// 4. Position node
const setPosition = {
  tool: "node_transform",
  arguments: {
    action: "set_property",
    uuid: "player-node-uuid",
    property: "position",
    value: { x: 0, y: 0, z: 0 }
  }
};

Working with Prefabs

// 1. Find a node to convert
const findNode = {
  tool: "node_query",
  arguments: {
    action: "find_by_name",
    name: "Enemy"
  }
};

// 2. Create prefab from node
const createPrefab = {
  tool: "prefab_lifecycle",
  arguments: {
    action: "create",
    nodeUuid: "enemy-node-uuid",
    savePath: "db://assets/prefabs/Enemy.prefab"
  }
};

// 3. Instantiate multiple times
const spawn1 = {
  tool: "prefab_instance",
  arguments: {
    action: "instantiate",
    prefabUuid: "enemy-prefab-uuid",
    position: { x: 100, y: 0, z: 0 }
  }
};

const spawn2 = {
  tool: "prefab_instance",
  arguments: {
    action: "instantiate",
    prefabUuid: "enemy-prefab-uuid",
    position: { x: -100, y: 0, z: 0 }
  }
};

Batch Node Operations

// 1. Find all enemy nodes
const findEnemies = {
  tool: "node_query",
  arguments: {
    action: "find_by_name",
    name: "Enemy",
    exactMatch: false  // Pattern match
  }
};
// Returns: [{ uuid: "enemy1-uuid" }, { uuid: "enemy2-uuid" }, ...]

// 2. Delete all enemies
// For each enemy uuid:
const deleteEnemy = {
  tool: "node_lifecycle",
  arguments: {
    action: "delete",
    uuid: "enemy-uuid"
  }
};

Scene Setup Workflow

// 1. Create new scene
const newScene = {
  tool: "scene_management",
  arguments: {
    action: "create_scene",
    name: "Level1",
    savePath: "db://assets/scenes/"
  }
};

// 2. Create background node
const background = {
  tool: "node_lifecycle",
  arguments: {
    action: "create",
    name: "Background",
    nodeType: "2DNode",
    components: [{
      type: "cc.Sprite",
      properties: {
        spriteFrame: "bg-texture-uuid"
      }
    }]
  }
};

// 3. Create UI canvas
const canvas = {
  tool: "node_lifecycle",
  arguments: {
    action: "create",
    name: "Canvas",
    nodeType: "2DNode",
    components: [{
      type: "cc.Canvas"
    }]
  }
};

// 4. Save scene
const saveScene = {
  tool: "scene_management",
  arguments: {
    action: "save_scene"
  }
};

Configuration

Server Settings

Access via MCP panel in Cocos Creator:

  • Port: Default 3000, customizable
  • Auto-start: Enable to launch server with editor
  • Tool Management: Selectively enable/disable specific tools

Tool Configuration

The plugin saves tool configurations in editor preferences. Enable/disable tools through the MCP panel's tool management tab.

Environment Variables

For external integrations, you can configure:

# MCP server endpoint
COCOS_MCP_URL=http://127.0.0.1:3000/mcp

# Project path (if automating multiple projects)
COCOS_PROJECT_PATH=/path/to/project

Troubleshooting

Server Won't Start

Issue: MCP server fails to start in Cocos Creator

Solutions:

  1. Check port is not in use: netstat -an | grep 3000
  2. Try different port in MCP panel settings
  3. Restart Cocos Creator
  4. Check extension is enabled in Extension Manager

Tool Calls Failing

Issue: AI can't execute tools or gets errors

Solutions:

  1. Verify server is running (check MCP panel status)
  2. Ensure scene is open (many tools require active scene)
  3. Check UUIDs are valid (use query tools first)
  4. Enable debug logging in console to see detailed errors

Component Removal Fails

Issue: Cannot remove component or script

Solution: Always use the exact cid (type field) from component_query:

// ✅ CORRECT
// First get component info
{ action: "get_components", nodeUuid: "node-uuid" }
// Returns: [{ type: "comp.MyScript!abc123", ... }]

// Then remove with exact cid
{
  action: "remove",
  nodeUuid: "node-uuid",
  componentType: "comp.MyScript!abc123"
}

// ❌ WRONG - Don't use script name
{
  action: "remove",
  nodeUuid: "node-uuid",
  componentType: "MyScript"  // Will fail!
}

Prefab References Lost

Issue: Prefab loses component or asset references

Solutions:

  • This was fixed in v1.4.0+
  • Ensure using latest plugin version
  • Internal references use {"__id__": x} format
  • External references set to null (as expected)
  • Asset references preserve UUID format

Connection Issues

Issue: MCP client can't connect to server

Solutions:

  1. Verify URL in client config matches server port
  2. Check firewall isn't blocking localhost connections
  3. Restart both Cocos Creator and MCP client
  4. Test with: curl http://127.0.0.1:3000/mcp

Performance Degradation

Issue: Editor becomes slow with MCP server

Solutions:

  1. Disable unused tools in tool management
  2. Reduce log levels in debug tools
  3. Limit query result counts
  4. Close unnecessary editor panels

Cross-Platform Path Issues

Issue: Asset paths don't work on different OS

Solution: Always use Cocos db:// protocol for asset paths:

// ✅ CORRECT - Cross-platform
"savePath": "db://assets/prefabs/MyPrefab.prefab"

// ❌ WRONG - Platform-specific
"savePath": "/Users/me/project/assets/prefabs/MyPrefab.prefab"

Advanced Usage

Custom Message Broadcasting

// Listen for custom events
const listen = {
  tool: "broadcast_message",
  arguments: {
    action: "listen",
    channel: "game-events"
  }
};

// Send custom messages
const broadcast = {
  tool: "broadcast_message",
  arguments: {
    action: "broadcast",
    channel: "game-events",
    message: { event: "player_died", score: 100 }
  }
};

Preferences Management

// Get editor preferences
const getPrefs = {
  tool: "preferences_manage",
  arguments: {
    action: "get",
    key: "editor.grid.snap"
  }
};

// Set preferences
const setPrefs = {
  tool: "preferences_manage",
  arguments: {
    action: "set",
    key: "editor.grid.snap",
    value: true
  }
};

System Information

// Get detailed system info
const systemInfo = {
  tool: "debug_system",
  arguments: {
    action: "get_info"
  }
};
// Returns: editor version, OS, memory, performance stats

Best Practices

  1. Always Query Before Modify: Use query tools to get UUIDs before operations
  2. Use Exact CIDs for Components: Never use script names for removal
  3. Save After Major Changes: Call save_scene after structural changes
  4. Validate UUIDs: Check UUIDs exist before referencing
  5. Use db:// Paths: Always use Cocos protocol for cross-platform compatibility
  6. Enable Only Needed Tools: Disable unused tools for better performance
  7. Test Prefabs After Creation: Instantiate and verify before distributing
  8. Handle Errors Gracefully: Check tool responses for success/failure

Resources

Version Compatibility

  • Plugin Version: 1.5.0+ recommended (1.4.0+ on GitHub)
  • Cocos Creator: 3.8.6 or higher
  • MCP Clients: Claude Desktop, Claude CLI, Cursor, VS Code (with MCP extensions)
  • Node.js: Not required (plugin runs in editor runtime)

FAQ

What does the cocos-creator-mcp-server skill do?

MCP server plugin for Cocos Creator 3.8+ that enables AI assistants to control the editor through 50 powerful tools for scenes, nodes, components, prefabs, and assets.

How do I install cocos-creator-mcp-server?

Run npx skills add https://github.com/reason-machines/mcp-skills --skill cocos-creator-mcp-server in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/cocos-creator-mcp-server/ (personal) or .claude/skills/cocos-creator-mcp-server/ (project).

Which AI agents can use cocos-creator-mcp-server?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is cocos-creator-mcp-server safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains cocos-creator-mcp-server?

It is published by reason-machines in reason-machines/mcp-skills. It has 221 recorded installs.

More from reason-machines/mcp-skills

View all →

codebase-memory-mcp-intelligence

reason-machines/mcp-skills

High-performance code intelligence MCP server that indexes codebases into knowledge graphs for structural queries, call traces, and architecture analysis

AI & Agents505 installs

playwright-mcp-server

reason-machines/mcp-skills

Browser automation MCP server using Playwright's accessibility tree for LLM-friendly web interaction

AI & Agents285 installs

tradingview-mcp-assistant

reason-machines/mcp-skills

Open the skill to read its SKILL.md instructions.

AI & Agents256 installs

lanhu-mcp-collaboration

reason-machines/mcp-skills

Open the skill to read its SKILL.md instructions.

AI & Agents245 installs

chrome-devtools-mcp-automation

reason-machines/mcp-skills

Expert guidance for Chrome DevTools MCP server - browser automation, debugging, and performance analysis for AI agents

AI & Agents239 installs

github-mcp-server

reason-machines/mcp-skills

Open the skill to read its SKILL.md instructions.

AI & Agents237 installs

Popular ai & agents skills

View category →

google-agents-cli-publish

google/agents-cli

This skill should be used when the user wants to "publish an agent", "publish my ADK agent", "register an agent with Gemini", "publish to Gemini" (formerly Gemini Enterprise), or needs guidance on the agents-cli publish gemini command. Also use when the user wants to "manage agents in Agent Registry", "list/update/delete registered agents", or "register an MCP server". Covers ADK vs A2A registration modes, programmatic and interactive usage, flag reference, auto-detection from deployment metadata, Agent Registry fleet management, and troubleshooting. Part of the agents-cli skills suite. Do NOT use for deployment (use google-agents-cli-deploy).

AI & Agents513.9K installs

google-agents-cli-eval

google/agents-cli

This skill should be used when the user wants to "run an evaluation", "evaluate my agent", "evaluate my ADK agent", "write an eval dataset", "analyze eval failures", "compare eval results", "optimize agent", or needs guidance on the Gemini platform eval methodology and the Quality Flywheel. Covers eval metrics, dataset schema, LLM-as-judge scoring, and common failure causes. Applies to any agents-cli project, whatever framework the agent is written in. Do NOT use for agent API code patterns (ADK: use google-agents-cli-adk-code), deployment (use google-agents-cli-deploy), or project scaffolding (use google-agents-cli-scaffold).

AI & Agents513.5K installs

skill-creator

anthropics/skills

Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.

OfficialAI & Agents416.4K installs

codex-pet

prime-skills/runcomfy-agent-skills

Codex Pet generator on RunComfy. Build a Codex-compatible Codex Pet spritesheet.webp + pet.json from a single reference image, drop it into ${CODEXHOME:-$HOME/.codex}/pets/ / and Codex picks it up as a custom Codex Pet next to the 8 built-ins. This skill produces the exact Codex Pet atlas Codex expects (1536x1872 PNG/WebP, 8 cols x 9 rows, 192x208 cells, 9 animation states — idle, running-right, running-left, waving, jumping, failed, waiting, running, review). Calls OpenAI GPT Image 2 edit ONCE via the local RunComfy CLI as runcomfy run openai/gpt-image-2/edit to produce a canonical Codex Pet pose, then assembles all 9 animation rows programmatically with ImageMagick micro-transforms — no Codex Pro, no $imagegen, no OPENAIAPIKEY required, only RUNCOMFYTOKEN. Triggers on "codex pet", "create codex pet", "make codex pet", "hatch codex pet", "/hatch image", "desktop pet codex", "codex pets", "spritesheet.webp", or any explicit ask to build a custom pet for OpenAI Codex.

AI & Agents402.1K installs

full-output-enforcement

leonxlnx/taste-skill

Overrides default LLM truncation behavior. Enforces complete code generation, bans placeholder patterns, and handles token-limit splits cleanly. Apply to any task requiring exhaustive, unabridged output.

AI & Agents401K installs

executing-plans

obra/superpowers

Use when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available

AI & Agents245.7K installs