Cocos MCP provides three dedicated screenshot tools—capture_scene_view, capture_editor_view, and capture_preview_view—that let AI clients see exactly what is on screen in Cocos Creator. These tools ship with the Funplay Cocos MCP extension and work over HTTP from any MCP-compatible client.
This article walks through how to use all three, when to switch from the core profile to the full profile, and what limitations to watch for.
What Is Cocos MCP and Why It Matters
Funplay Cocos MCP is an extension for Cocos Creator that exposes editor and runtime functionality to AI coding assistants through the Model Context Protocol. In its full profile, it offers 67 tools covering scene manipulation, prefab workflows, asset management, UI authoring, runtime control, input simulation, and screenshots. The core profile ships 19 tools, including capture_scene_view.
The extension requires Cocos Creator 3.8 or later. After installation, an MCP Server panel appears inside the editor. Click Start Server and the HTTP endpoint begins listening, ready for any MCP-compatible client to connect.
For context, the sibling projects in the same family are larger: Unity MCP exposes 79 tools and requires Unity 2022.3 or later, while Godot MCP exposes 105 tools and requires Godot 4.2 or later. All three share the same architecture—an HTTP server running inside the editor, bridging AI clients to engine internals.
Installing the Extension
There are two installation paths.
Option 1: Project-level extension. Clone the repository into your project's extensions/ folder:
cd your-project/extensions
git clone https://github.com/FunplayAI/funplay-cocos-mcp.git
Then open Cocos Creator, go to Extension → Extension Manager → Refresh. The MCP Server panel should appear.
Option 2: Global extension. Place the cloned folder at ~/.CocosCreator/extensions/. This makes the server available across all projects.
After installation, open the MCP Server panel in the editor and click Start Server. The server starts at 127.0.0.1 on port 8765.
Configuring Your AI Client
The MCP Server panel offers one-click configuration for several clients:
- Claude Code
- Claude Desktop
- Cursor
- VS Code (Copilot or the MCP extension)
- Codex CLI
- Trae
- Kiro
Click the button for your client in the panel. The extension writes the correct configuration file automatically. Restart your AI client if it was already running.
Understanding the Two Tool Profiles
The extension ships two profiles that control how many tools are exposed.
Core profile (19 tools). This is the default. It centers on execute_javascript plus a curated set of essentials: get_scene_info, get_node_info, create_node, delete_node, find_nodes, list_prefabs, capture_scene_view, get_preview_state, enter_preview, and exit_preview. Only one of the three screenshot tools is available here.
Full profile (67 tools). This adds narrow, typed tools across all 13 categories. All three screenshot tools are available in this mode.
Switch profiles in the MCP Server panel inside Cocos Creator. Change the dropdown from core to full and restart the server.
The Three Screenshot Tools
Each tool captures a different view inside Cocos Creator. Here is what each one does and when to use it.
capture_scene_view
This is the only screenshot tool available in the core profile. It captures the Scene panel—the main editing canvas where you place and arrange nodes. Think of it as photographing what the developer sees while building a level.
Use it when:
- You want an AI assistant to verify that nodes are positioned correctly after a script creates them.
- You need visual confirmation of layout changes without switching back to the editor.
- You are iterating on scene composition and want the AI to "see" the current state.
In the core profile, you can call this tool directly. Your AI client sends the request over HTTP to 127.0.0.1:8765, and the server returns a screenshot image.
capture_editor_view
This tool is available only in the full profile. It captures the entire Cocos Creator editor window—panels, hierarchies, inspectors, the works. It is broader than the scene view because it includes UI chrome.
Use it when:
- You need to verify that a panel or inspector shows the expected values.
- You want to confirm an extension loaded correctly and its panel is visible.
- You are debugging why a tool call did not produce the expected result and need full visual context.
Switch to the full profile in the MCP Server panel before calling this tool. If you are still on the core profile, the tool will not be listed.
capture_preview_view
Also available only in the full profile, this tool captures the game's running preview. It only works when the preview is active. If the editor is not in preview mode, there is nothing to capture.
Use it when:
- You want the AI to see what the player sees at runtime.
- You need to verify animations, particle effects, or UI behavior during gameplay.
- You are running input simulation and want visual proof that the simulated touch or click registered.
The typical workflow combines enter_preview, a short delay or input simulation, then capture_preview_view, and finally exit_preview.
Walkthrough: Capturing All Three Views
Here is a concrete session using Claude Code as the client with the full profile enabled.
First, confirm the server is running. In your terminal:
curl http://127.0.0.1:8765/health
You should get a response indicating the server is alive.
Now, in your AI client, ask it to capture each view. The client translates your request into MCP tool calls. Here is what the underlying JSON-RPC calls look like:
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "capture_scene_view",
"arguments": {}
}
}
The server responds with a base64-encoded image. Your AI client decodes and displays it inline.
To capture the editor view:
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "capture_editor_view",
"arguments": {}
}
}
To capture the preview view, you need to enter preview mode first:
{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "enter_preview",
"arguments": {}
}
}
Wait a moment for the preview to render, then:
{
"jsonrpc": "2.0",
"id": 4,
"method": "tools/call",
"params": {
"name": "capture_preview_view",
"arguments": {}
}
}
When you are done:
{
"jsonrpc": "2.0",
"id": 5,
"method": "tools/call",
"params": {
"name": "exit_preview",
"arguments": {}
}
}
In practice, you do not write these calls yourself. Your AI client handles the protocol. You simply say "take a screenshot of the scene" or "show me what the preview looks like" and the client calls the correct tool.
Practical Tips
Profile switching mid-session. If you switch from core to full, restart the server. Your AI client may also need to reconnect to pick up the expanded tool list. Some clients reconnect automatically; others require a manual restart.
Preview capture timing. The preview view needs a running game. Call enter_preview first, wait for the game to load, then capture. If you call capture_preview_view too quickly, you may get a blank frame or an error.
Image size. Screenshots reflect the current size of the captured panel. Resize your Scene panel or editor window before capturing if you need higher resolution. The tool captures pixels as-is.
Combining with other tools. Screenshots are most useful when paired with scene manipulation. A common pattern: have the AI create nodes, rearrange the scene, capture the scene view to verify placement, then adjust. This visual feedback loop is where MCP screenshots add real value over text-only tool responses.
Gotchas and Limitations
Core profile limits you to one screenshot tool. If you need capture_editor_view or capture_preview_view, you must switch to the full profile. There is no way to cherry-pick individual tools from the full set while staying on core.
No CLI. The Cocos MCP does not ship a command-line interface. The editor panel is the primary way to start and stop the server. You cannot script the server itself from the terminal. Any MCP-compatible client connects over HTTP, but the server must be running inside Cocos Creator.
No screenshots without the editor. Because the server runs inside Cocos Creator, the editor must be open and the server started manually. Headless or CI environments are not supported.
Platform and version. The extension requires Cocos Creator 3.8 or later. Older versions will not load the extension. There is no CLI fallback or standalone binary.
Token cost. Each screenshot is a full image sent to your AI client. If your client processes images as tokens, frequent captures add up quickly. Be intentional about when you request a screenshot rather than requesting one on every tool call.
When Not to Use This
If you only need text descriptions of scene hierarchy, use get_scene_info or get_node_info instead. These return structured data without the token cost of an image. Save screenshots for cases where layout, visual correctness, or runtime appearance matters.
If you are building an automated pipeline that runs without a human at the editor, the requirement for a running Cocos Creator instance makes this extension the wrong fit. Consider scripting the Cocos Creator build system directly instead.
Related Resources
- The primary repository: funplay-cocos-mcp
- The sibling Unity extension: funplay-unity-mcp (79 tools, Unity 2022.3+)
- The sibling Godot extension: funplay-godot-mcp (105 tools, Godot 4.2+)
- More articles on AI-assisted game development: gamebooom.ai/en/blog
Install the extension, switch to the full profile, and start capturing screenshots from your AI client today.