convez.ai
MCP ServerProdutividadeIntermediário
shiliyu1991-lang

Cocos MCP 3x

shiliyu1991-lang/cocos-mcp-3x

Bridge MCP para Cocos Creator — integre Claude/Cursor ao seu editor

Ver no GitHub
BomPluginScore · de 0 a 100

Servidor MCP que conecta clientes LLM (Claude, Cursor) ao editor Cocos Creator 3.8.x. Permite que modelos de IA inspecionem e manipulem cenas, nós, assets e scripts do projeto de jogo em tempo real via WebSocket.

Instalação

$npx convez-ai shiliyu1991-lang/cocos-mcp-3x

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
18
Forks
6
Acompanhando
1
Saúde
42%
Último commit
há 4 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Gerar e modificar cenas e nós de jogo com assistência de IA
  • Inspecionar e automatizar manipulação de assets do projeto
  • Executar scripts e operações no editor via prompt em linguagem natural
  • Assistência contextual durante desenvolvimento de games

Veredito

MCP bem estruturado e prático para game developers que usam Cocos Creator. Auto-contido (sem dependências npm), suporta múltiplos clientes MCP e oferece acesso profundo à API do editor — excelente para automação de fluxos criados/técnicos.

README

A tradução para o português deste README ainda está na fila.

cocos-mcp-3x

English · 中文

An editor extension that connects an LLM (Claude Desktop / Cursor or any MCP client) to the Cocos Creator 3.8.x editor, letting the model inspect and drive your game project: read/write nodes, operate on assets and scenes, read the console, and execute scripts.

The plugin is self-contained: the Python MCP server is bundled inside the plugin at ./server, and the extension itself has no npm dependencies and no build step.

How it works

MCP client (Claude / Cursor)
        │  stdio / http
        ▼
Python FastMCP server  ── server/src/main.py
        │  WebSocket bridge  127.0.0.1:6020/cocosmcp
        ▼
Cocos Creator extension ── main.js (connects in as the WS client)
        │  Editor.Message.request(...)
        ▼
   Cocos editor (asset-db / scene API)
  • The Python side is the WebSocket server; the Cocos extension is the client and dials in via the Connect button on the panel.
  • Each tool call sends a JSON envelope over the bridge to the extension, which dispatches by command name to the matching handler, runs the editor operation, and replies {id, success, data|error}.

Tools provided

ToolPurpose
get_project_infoProject path, assets root, editor version, scene list, available bridge commands
manage_sceneList / open / save scenes (Cocos 3.x .scene)
manage_nodeInspect or modify nodes in the current scene (mostly addressed by uuid)
manage_assetInspect and manipulate assets under assets/ via the asset-db
read_consoleRead / clear the editor console (500-entry ring buffer)
execute_scriptExecute arbitrary JS in the editor main or scene context (powerful escape hatch)

Install into a project

Drop the whole cocos-mcp-3x folder into your Cocos project's extensions/ directory:

<your-project>/extensions/cocos-mcp-3x/

During development you can use a directory junction pointing at the plugin source so edits take effect immediately: mklink /J "<project>\extensions\cocos-mcp-3x" "<plugin-source-path>"

After restarting the editor (or reloading the extension), Cocos MCP → Open Panel appears in the menu.

First run: create the Python environment

Requires Python 3.10+ on your machine. Create a virtual environment inside the plugin's server directory and install the dependencies:

cd cocos-mcp-3x\server
python -m venv .venv
.venv\Scripts\python -m pip install -e .

Behind a slow/blocked PyPI (e.g. in mainland China), the install often times out. Add a mirror:

.venv\Scripts\python -m pip install -e . -i https://pypi.tuna.tsinghua.edu.cn/simple

.venv is not distributed with the repo (its pyvenv.cfg hardcodes the local Python path and it is large). Recreate it locally with the step above — the panel also surfaces this exact command when it can't find python.exe.

Dependencies: fastmcp>=2.0.0, websockets>=12.0 (install .[dev] to also get pytest, pytest-asyncio).

Using the panel

  1. Open the panel: menu Cocos MCP → Open Panel.
  2. Server dir empty = use the plugin's bundled ./server (recommended). Only fill in an absolute path to override when the server lives elsewhere.
  3. Click Start Server; the hint line showing python: found means it's ready.
  4. Click Connect; a green dot means the WebSocket bridge is connected.

Configure the MCP client

The server entry point is server/src/main.py and supports two transports — stdio (client default) and http (manual testing):

cd cocos-mcp-3x/server/src
python -m main --transport stdio                    # Claude Desktop / Cursor
python -m main --transport http --http-port 8765    # manual testing

Environment variables (precedence: CLI args > env vars > defaults):

VariableDefault
COCOS_MCP_BRIDGE_HOST127.0.0.1
COCOS_MCP_BRIDGE_PORT6020
COCOS_MCP_BRIDGE_PATH/cocosmcp
COCOS_MCP_REQUEST_TIMEOUT30 (seconds)
COCOS_MCP_CONNECT_TIMEOUT5 (seconds)

Troubleshooting

SymptomCause / fix
Panel shows python: NOT FOUNDserver\.venv isn't created yet. Run the "first run" venv steps above; the panel re-checks every 1.5s.
pip install keeps timing outPyPI unreachable. Add a mirror, e.g. -i https://pypi.tuna.tsinghua.edu.cn/simple.
Start Server says port in use / not listeningChange Bridge port (default 6020) or HTTP port (default 8799) to a free port, then Start. Server URL follows the Bridge port automatically.
Confused by the two portsBridge port is the internal WebSocket channel (extension ↔ Python server); HTTP port is what the MCP client connects to (http://127.0.0.1:8799/mcp/).
Connect won't turn greenMake sure Start Server is running, and Connect uses the same Bridge port you started with.
No Cocos MCP menuEnsure the plugin is under the project's extensions/, then reload the extension or restart the editor.

Directory layout

cocos-mcp-3x/
├── main.js            Extension main process (WebSocket client + command handlers)
├── panel/index.js     Panel UI (start server / connect)
├── scene.js           Scene-context script (evalInScene)
├── package.json
├── SETUP.md           Detailed install & distribution notes
└── server/            Bundled Python MCP server
    ├── src/           Entry main.py; core/transport/services/utils
    ├── pyproject.toml
    └── .venv/         Python virtual environment (generated locally, not committed)

Extending: add a tool

  1. Create server/src/services/tools/<name>.py, decorate an async function with @cocos_mcp_tool(description=...), and return await call_bridge("<name>", params) (see get_project_info.py). No manual registration — tools are auto-discovered on startup.
  2. Add a matching command handler in main.js. Both ends must agree on the command name and param shape.

Requirements

  • Cocos Creator 3.8.0+
  • Python 3.10+

License

MIT

Ver o original no GitHub

Bom para

Relacionados