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/"