Funplay MCP for Cocos

An Embedded MCP Server for Cocos Creator Editor

中文 | English

If this project helps your Cocos workflow, please consider giving it a Star. It helps more developers discover the project and supports ongoing development.

Funplay MCP for Cocos is an MIT-licensed Cocos Creator extension that embeds an HTTP MCP server directly inside the editor. It lets AI assistants such as Claude Code, Cursor, Codex, VS Code Copilot, Trae, Kiro, Qoder, Kimi Code, and OpenCode inspect and operate your running Cocos project.

The package follows the same product direction as Funplay MCP for Unity: keep the default tool surface focused, provide a one-click client configuration window, and make one high-flexibility execution tool the primary workflow.

For Cocos, the primary tool is execute_javascript:

• context: "scene" runs JavaScript in the active Cocos scene/runtime context
• context: "editor" runs JavaScript in the Cocos editor/browser context

"Create a login page UI with account/password fields and a main login button."

Your AI assistant can call execute_javascript, build the UI hierarchy under the active Canvas, attach Cocos components, inspect the result, and capture a screenshot for validation.

Quick Start

If you just want to connect quickly, do these three things:

• Install this repository as a Cocos Creator extension
• Open Funplay > MCP Server
• Use the built-in one-click MCP client configuration

1. Install as a Cocos Creator Extension

Recommended install: use the official Cocos Store page and install the extension into your target Cocos Creator project.

For local development or unreleased builds, clone or copy this repository into your Cocos project extension directory:

cd /path/to/your-cocos-project
mkdir -p extensions
git clone https://github.com/FunplayAI/funplay-cocos-mcp.git extensions/funplay-cocos-mcp

Then restart Cocos Creator or reload extensions from the editor.

For a non-git install, download Funplay.CocosMcp.v<version>.zip from the GitHub Releases page, unzip it, and move the extracted funplay-cocos-mcp folder into your project extensions/ directory.

Install for All Projects (Recommended)

Install and open the extension in any project first. Then open Funplay > MCP Settings and click Install for All Projects in the All Projects section. The extension downloads the latest GitHub Release, verifies SHA256SUMS.txt, and installs it into the active Cocos Creator version's managed global extension directory:

• macOS / Linux: ~/.CocosCreator/builtin-extensions/<Creator version>/funplay-cocos-mcp
• Windows: %USERPROFILE%\.CocosCreator\builtin-extensions\<Creator version>\funplay-cocos-mcp

Cocos Creator scans and registers the installed copy immediately. Projects opened or created with that Creator version then load it automatically, and the MCP server keeps its default autostart behavior. Reopen an already-running project if its project-level copy has priority. No extension files are copied into each project's extensions/ directory.

Global extensions are isolated by Cocos Creator version. If you use multiple Creator versions, run Install for All Projects once from each version.

The installer does not delete the current project copy, which protects development worktrees. If both copies exist, MCP Settings shows a duplicate-install warning. After confirming that the global copy works, remove or disable the project copy to avoid extension conflicts.

2. Start the MCP Server

Open the editor menu:

Funplay > MCP Server

New projects get a stable project-derived port in 20000–29999. Existing saved configurations keep their fixed port (including 8765). Use the exact URL shown in MCP Server; if a temporary fallback port is active, click Pin Current Port or Use Per-Project Port before configuring a client.

If the configured port is already occupied, the extension first checks whether the existing listener belongs to the same Cocos project. Same-project listeners are reused safely; unrelated listeners trigger automatic fallback to the next available local port.

The panel is intentionally small:

• Enable or disable the MCP server
• Open focused Tool Exposure, MCP Settings, and Project Skills windows
• Automatically check the installed version against the latest GitHub release
• Open the release page or install verified release packages from the panel
• Install once in the Cocos Creator global extensions directory so existing and new projects can use it automatically
• Configure AI clients with one click and preview the selected client config
• Keep advanced tool profile editing, transport settings, and installation management out of the main server window
• Follow the Cocos Creator interface language automatically, or select Chinese/English per project in MCP Settings
• Toggle Print MCP logs in Settings to silence MCP console messages without losing Recent Activity or internal diagnostics

All management pages use consistent headings, aligned controls, and lightweight sections. Tool Exposure groups per-tool toggles by category; Project Skills highlights available actions and folds away file paths and backups. Recent Activity shows each call's summary and actual result as an expandable object/array tree, with execution logs and return values in separate sections for scripts. Output sections and the standalone log-viewing panel are removed. Short action notices preserve success/failure feedback, while diagnostic logs remain available to MCP tools and resources.

Script tools capture per-call console.log/info/warn/error/debug output, including logs before a failure, independently of Print MCP logs. Capture is isolated across concurrent and nested calls and stops when the script settles; global/project logs and logs from separately required modules are not collected. Use the injected console (also available as env.console in run/module exports). MCP responses retain their existing data shape and add optional execution metadata with context, duration, bounded/redacted logs, and an omitted-entry count. Recent Activity preserves result hierarchy and scalar values; large results and file/script bodies remain limited or omitted, with truncation notices.

The extension menu and native panel titles follow the Cocos Creator interface language. Panel controls, tool descriptions, status messages, prompts, and empty states support English and Chinese; open Funplay > MCP Settings to follow Creator or set a project-specific content-language override. MCP tool IDs and schemas remain in English so client integrations stay stable.

3. Configure Your AI Client

Use the built-in MCP Client Config section in the Funplay > MCP Server panel first.

Select your target client, click One-Click Configure, and the extension writes the recommended MCP config entry for you.

The MCP server name written to clients is:

cocos-<project>-<hash>

If you prefer to edit config files manually, use the examples below as fallback references. Replace their legacy funplay_cocos name and 8765 port with the name and URL shown in your panel. One-click Claude Code configuration uses the project's Git-root scope in ~/.claude.json, not the global example below. See project setup and migration.

{
  "mcpServers": {
    "funplay_cocos": {
      "type": "http",
      "url": "http://127.0.0.1:8765/"
    }
  }
}

{
  "mcpServers": {
    "funplay_cocos": {
      "url": "http://127.0.0.1:8765/"
    }
  }
}

{
  "servers": {
    "funplay_cocos": {
      "type": "http",
      "url": "http://127.0.0.1:8765/"
    }
  }
}

{
  "mcpServers": {
    "funplay_cocos": {
      "url": "http://127.0.0.1:8765/"
    }
  }
}

{
  "mcpServers": {
    "funplay_cocos": {
      "type": "http",
      "url": "http://127.0.0.1:8765/"
    }
  }
}

{
  "mcpServers": {
    "funplay_cocos": {
      "type": "http",
      "url": "http://127.0.0.1:8765/"
    }
  }
}

{
  "mcpServers": {
    "funplay_cocos": {
      "url": "http://127.0.0.1:8765/"
    }
  }
}

[mcp_servers.funplay_cocos]
url = "http://127.0.0.1:8765/"

{
  "mcp": {
    "funplay_cocos": {
      "type": "remote",
      "url": "http://127.0.0.1:8765/"
    }
  }
}

Optional: npm stdio Wrapper

If your MCP client prefers a local stdio command, install the npm wrapper after starting the Cocos editor server:

npm install -g funplay-cocos-mcp

Example MCP client entry:

{
  "mcpServers": {
    "funplay_cocos": {
      "command": "funplay-cocos-mcp",
      "env": {
        "FUNPLAY_COCOS_MCP_URL": "http://127.0.0.1:8765/"
      }
    }
  }
}

The wrapper bridges stdio MCP traffic to the embedded Cocos HTTP endpoint. You can also run it with npx funplay-cocos-mcp --url http://127.0.0.1:8765/.

4. Verify the Connection

Open your AI client and try a few safe requests first:

• "Call get_project_info and summarize the current Cocos project."
• "Read cocos://project/context and tell me the editor status."
• "Use execute_javascript with context: \"scene\" to return the active scene name."
• "Use execute_javascript with context: \"editor\" to return the project path."

If these work, the MCP server, resources, prompts, and primary execution tool are connected correctly.

For local transport debugging, the panel can copy these commands, or you can run them directly:

curl http://127.0.0.1:8765/health
curl http://127.0.0.1:8765/tools

5. Start Building

Try a higher-level prompt in your AI client:

Create a login page UI in the current Cocos scene with account/password fields, a login button, and a guest-login button. Use execute_javascript first, inspect the hierarchy, then capture a screenshot.

Before You Start

• This extension is Editor-only. It is meant to automate Cocos Creator, not to add runtime dependencies to your final game build.
• New projects use a project-derived port. The MCP Server dashboard shows the exact endpoint and supports pinning a fixed port.
• If the configured port is busy, the server automatically falls back to the next available port and the panel/client config use the actual running port.
• GET /health and GET /tools are read-only debug endpoints for quick local checks outside an MCP client.
• The default core profile exposes 39 high-signal tools. Switch to full for all 105 tools, or use custom to include/exclude tool categories and individual tools.
• The panel checks GitHub releases automatically and also supports manual checks.
• One-click update downloads the GitHub Release zip, verifies SHA256SUMS.txt, backs up the current extension, replaces the package files, and reloads the extension when the Cocos package API supports it. If reload is unavailable, restart Cocos Creator after installation. Git worktree and symlink installs are intentionally left to manual git pull or package replacement.
• Install for All Projects uses the same release and SHA256 verification flow, targets the active Creator version's managed global directory, then asks Creator to scan and register the package. It preserves an active project copy instead of switching packages underneath an open settings window; the global copy is enabled immediately when no project copy is active, or on the next project open otherwise.
• Project Skills manages the built-in funplay-cocos-mcp-workflow and funplay-cocos-ui-composition skills plus custom skills for Codex, Claude Code, Cursor, Qoder, and Kimi Code. Select a client to see its managed directory, versions, diffs, local modifications, backups, and restore actions. Legacy Codex built-ins can migrate to .agents/skills without deleting their original files.
• Streamable HTTP responses follow the MCP transport requirements for Accept, MCP-Protocol-Version, JSON-RPC notifications/responses, and optional Mcp-Session-Id sessions.
• Tool listings include MCP outputSchema and annotations; structured tool results use a standard envelope with ok, tool, callId, summary, data, and follow-up refs.
• execute_javascript safety checks are enabled by default. They block obvious risky filesystem and shell patterns such as delete/truncate calls, raw writable streams, path traversal, user/system absolute paths, and child_process. This is a guardrail, not a full sandbox; a call can explicitly pass safety_checks: false when you have reviewed the risk.
• All exposed MCP tools execute directly. There is no extra approval toggle inside the Cocos extension.
• File tools and cocos://asset/path/... resources are restricted to the active Cocos project root.
• The recommended workflow is execute_javascript first, then focused helper tools for screenshots, diagnostics, assets, and inspection.
• If you change the server port or tool exposure in the panel, the extension saves the config and restarts the server when needed.

Why This Project

• execute_javascript First — One high-flexibility JavaScript tool can orchestrate scene/runtime work and editor-side automation without flooding AI clients with too many narrow tool calls
• Embedded Cocos Extension — No separate Python daemon or external bridge process is required for the Cocos-side plugin
• One-Click Client Configuration — Configure Claude Code, Cursor, VS Code, Trae, Kiro, Qoder, Kimi Code, Codex, and OpenCode directly from Cocos Creator
• Project Context Built In — Exposes live project, scene, selection, script diagnostics, logs, and interaction-history resources
• Focused by Default, Full When Needed — core reduces tool-list noise; full exposes every available tool; custom plus saved profiles lets you tune and restore tool exposure by category or tool
• Visual Validation — Scene/editor/preview screenshots and input simulation help AI verify UI and gameplay changes

Highlights

• 105 Built-in Tools — Scene hierarchy, editor state, selection workflows, prefabs, assets, asset dependencies, project instructions, UI creation, components, files, logs, script diagnostics, screenshots, runtime control, build/preview helpers, editor preferences, event binding, and input simulation
• Primary Unified Tool — execute_javascript supports both scene and editor contexts
• Resources & Prompts — Live project/log resources plus reusable workflows like script fixing, scene validation, and playable prototype creation
• Cocos Panel UI — A compact Funplay > MCP Server dashboard plus focused Tool Exposure, MCP Settings, and Project Skills windows for larger workflows
• Screenshot and Input Support — Capture editor/scene/game/preview screenshots and send Electron-level mouse/keyboard events
• Vendor Agnostic — Works with any AI client that supports MCP over HTTP JSON-RPC

Relationship to Funplay MCP for Unity

Funplay MCP for Cocos follows the same design principles as Funplay MCP for Unity, adapted to Cocos Creator's JavaScript/TypeScript editor environment.

MCP Capabilities

The current package exposes four capability layers:

• Tools — 39 tools in core, 105 tools in full, plus custom include/exclude rules and saved tool profiles
• Primary execution — execute_javascript for scene/runtime and editor/browser automation
• Prompts — fix_script_errors, create_playable_prototype, scene_validation, and auto_wire_scene, plus parameterized project workflows loaded from mcp-prompts/*.md. See project isolation, Skills and workflow setup.
• Resources — project context, scene summaries, current selection, script diagnostics, asset selection, logs, and MCP interaction history

For the generated tool reference, including categories, profiles, and read/mutation hints, see docs/TOOLS.md.

The default core set is intentionally small: execute_javascript, execute_scene_script, execute_editor_script, get_editor_state, get_tool_catalog, check_for_updates, get_selection, list_project_instructions, read_project_instruction, set_selection, get_project_info, get_build_status, get_preview_mode, create_scene, get_scene_info, get_hierarchy, list_scenes, open_scene, inspect_prefab, validate_prefab_references, inspect_prefab_instance, list_assets, inspect_asset, inspect_asset_dependencies, validate_asset_dependencies, open_asset, select_asset, run_script_diagnostics, get_recent_logs, search_project_logs, clear_logs, validate_scene, get_performance_snapshot, get_script_diagnostic_context, get_runtime_state, capture_editor_screenshot, capture_scene_screenshot, capture_preview_screenshot, and list_editor_windows.

Preview Modes

Creator 3.8.x preview automation uses the same modes and editor APIs as the built-in preview toolbar:

Use get_preview_mode to inspect the active mode, set_preview_mode to switch it, and run_project_preview to start it. run_project_preview still accepts platform as a deprecated alias for mode.

Game View starts through the native preview toolbar so its manual Pause/Resume buttons remain usable. Repeated starts leave an existing preview running (including its paused state). pause_runtime and resume_runtime control that same Game View preview and are idempotent; they require a running Game View and do not control browser/simulator previews or the edit-scene director. Switching away from Game View stops it through the toolbar first; rejected operations report an error instead of claiming success.

Enable these control tools in full or a custom tool profile. When scripting, prefer them over directly calling scene.editor-preview-set-play, which bypasses toolbar synchronization.

get_runtime_state (also used by validate_scene) reports scope: "gameView", actual running/paused values, busy, and toolbarSynchronized. It no longer presents edit-scene frame/time-scale counters as preview state; those remain in get_performance_snapshot.runtime with scope: "editScene". set_time_scale continues to affect only the edit scene. Preview controls require a compatible, ready Creator main-window toolbar; an unavailable toolbar produces an explicit error.

Browser preview results distinguish same-host automation from LAN access:

Built-in Resources

Built-in Tools

Funplay MCP for Cocos currently ships with 105 tool functions in the full profile:

Primary Tool Examples

Scene Context

{
  "context": "scene",
  "code": "return { sceneName: scene.name, rootCount: scene.children.length };",
  "args": {}
}

Editor Context

{
  "context": "editor",
  "code": "return { projectPath: context.projectPath, toolCount: helpers.listTools().length };",
  "args": {}
}

Editor-context scripts receive Editor, fs, path, os, require, context, args, and helper functions such as helpers.getStatus(), helpers.listTools(), helpers.readResource(uri), helpers.callTool(name, args), and helpers.configureClient(targetId).

Optional Configuration

Place funplay-cocos-mcp.config.json in the Cocos project root:

{
  "host": "127.0.0.1",
  "port": 8765,
  "toolProfile": "core",
  "enabledToolCategories": [],
  "disabledToolCategories": [],
  "enabledTools": [],
  "disabledTools": [],
  "enableSessions": false,
  "enableConsoleLogging": true,
  "executeJavascriptSafetyChecks": true,
  "autostart": true,
  "maxInteractionLogEntries": 50,
  "activeToolProfileName": "",
  "savedToolProfiles": []
}

Environment variables are also supported:

• COCOS_MCP_HOST
• COCOS_MCP_PORT
• COCOS_MCP_PROFILE

toolProfile: "custom" starts from the core set, then adds enabledToolCategories / enabledTools and removes disabledToolCategories / disabledTools. The panel can save these exposure settings as named savedToolProfiles for quick restore or sharing. enableSessions is off by default because this server does not need cross-request client state for normal editor automation.

enableConsoleLogging defaults to true. Turn it off in MCP Settings > Console Logs > Print MCP logs to stop the extension and HTTP server from printing MCP information, warnings, and errors to the Cocos console. It takes effect immediately, persists per project, and does not restart MCP, clear history, mute project-script logs, or change stdio protocol output.

Architecture

Cocos Creator Extension
    ├─ browser.js
    │   ├─ Embedded HTTP MCP Server
    │   ├─ Tool Registry
    │   ├─ Resource Provider
    │   ├─ Prompt Provider
    │   └─ One-Click Client Configuration
    ├─ scene.js
    │   └─ Scene/runtime execution bridge
    ├─ panel/index.js
    │   └─ Minimal MCP Server dashboard
    ├─ panel/tool-exposure.js, panel/settings.js, panel/project-skills.js
    │   └─ Focused maintenance windows
    └─ lib/
        ├─ assets, diagnostics, screenshots, input
        ├─ tool-profiles, javascript-safety
        ├─ tools/
        │   ├─ files
        │   ├─ assets-advanced
        │   ├─ cocos-project
        │   └─ scene-events
        └─ server, resources, prompts, tool registry

The server speaks MCP-style HTTP JSON-RPC 2.0 and supports tools, resources, resource templates, prompts, health checks, and a read-only /tools debug endpoint.

Development

Run checks before publishing changes:

npm run check
npm test
npm run docs:check
npm run release:check
npm run pack:dry-run

Regenerate the tool reference after changing lib/tool-registry.js:

npm run docs:generate

To generate a GitHub Release-ready extension package:

npm run release:package

The package is written to releases/<version>/ with a zip, manifest, generated release notes, checksum file, and release README. Upload all five files so the public checksums can be verified. See RELEASE_WORKFLOW.md and RELEASE_CHECKLIST.md for the full process.

Validate MCP Registry metadata before publishing:

npm run registry:validate

License

MIT License. See LICENSE.