跳到主要内容

MCP 服务器

PlayCanvas Editor MCP Server 将 AI 助手连接到已打开的编辑器会话，可以修改项目数据，并通过视口或运行中的应用验证结果。

MCP 客户端启动本地服务器，编辑器再连接到它。绝大多数工具操作当前编辑器中打开的项目。少量项目工具还可列出、创建、更新和打开已登录账号的项目，因此即使尚未打开项目，助手也能从项目仪表盘开始工作。

一次性安装服务器​

配置 MCP 客户端前，请安装 Node.js 22.18 或更高版本。以下命令通过 npx 使用已发布的 @playcanvas/editor-mcp-server 包。

Claude Code​

claude mcp add playcanvas -- npx -y @playcanvas/editor-mcp-server

Codex​

codex mcp add playcanvas -- npx -y @playcanvas/editor-mcp-server

在 Windows 上运行：

codex mcp add playcanvas -- cmd /c npx -y @playcanvas/editor-mcp-server

Cursor 与 Claude Desktop​

将此服务器添加到客户端的 MCP 配置：

{
  "mcpServers": {
    "playcanvas": {
      "command": "npx",
      "args": ["-y", "@playcanvas/editor-mcp-server"]
    }
  }
}

在 Cursor 中打开 Settings > Cursor Settings > MCP；在 Claude Desktop 中打开 Settings > Developer > Edit Config。修改配置后重启客户端。

Windows 系统

Windows 上采用 JSON 配置的客户端应使用 "command": "cmd"，并在 args 数组最前面添加 "/c"。

连接项目​

  1. 在 PlayCanvas 编辑器中打开项目。
  2. 单击编辑器工具栏底部的 MCP。
  3. 确认端口为 52000，单击 Connect。
编辑器 MCP 服务器连接面板

使用连接期间请保持 MCP 客户端运行。同一时间只有一个编辑器实例能连接到服务器，因此切换项目或浏览器标签页前，应先断开其他编辑器。

浏览器权限

Chromium 浏览器在允许网站访问本机服务器前会请求许可，Chrome 142 起如此，Chrome 147 将其扩展到编辑器使用的连接。出现提示时选择 Allow，或打开地址栏锁形菜单并允许 Apps on device。只有编辑器需要此权限，启动页会通过编辑器桥接。连接被阻止时可能静默失败，看起来与服务器未运行相同。

要使用其他端口，在服务器参数后添加 --port <number>，并在编辑器中输入相同端口。

从项目仪表盘连接​

playcanvas.com/editor 的项目仪表盘在侧栏底部账号行提供 MCP server 按钮。单击打开面板，查看 Status 和 Port，再选择 Connect。

MCP 服务器

连接会被记住。无论由你还是助手打开项目，标签页进入项目后，编辑器都会在加载时自动重连，无需再次点击。

管理项目​

连接项目仪表盘或项目后，助手可以管理已登录账号的项目：

工具功能
list_projects列出你或组织的项目及其 ID。
get_project读取指定项目摘要，未提供 ID 时读取当前编辑器中的项目。
create_project创建项目，设置 open 可在就绪后打开。
update_project修改项目名称、描述或可见性。
open_project在已连接标签页中打开项目，标签页会重新加载，编辑器随后重连。

仅支持设置 name、description、private 和 owner（用户名），其他字段会按名称拒绝。套餐限制仍然适用，私有项目需要付费套餐。项目仪表盘没有打开的项目，因此在助手打开项目之前，场景和资源工具会报告这一状态。

列出我的 PlayCanvas 项目。创建名为“Cube Garden”的项目并打开，在场景中的盒体周围
添加十个彩色立方体，排列成圆环。
备注

项目工具需要高于 0.7.1 的 Editor MCP Server，以及编辑器 2.35 或更高版本。

先以只读操作检查连接​

先提出只读请求，确认助手看到的是目标编辑器，并在修改前获得上下文。

检查当前通过 PlayCanvas MCP 连接的项目，报告已加载场景、当前选择和版本控制状态。
不要进行任何修改。

如果助手报告的场景或项目不正确，请先连接正确的编辑器标签页再继续。

创建恢复点​

MCP 会直接修改编辑器项目，没有本地 Push 步骤。较大任务开始前请创建检查点。

检查当前版本控制状态。如果项目已准备好修改，创建名为“Before lighting update”的检查点。
暂时不要切换分支、重置状态或修改场景。

如果其他协作者有未保存工作，或项目状态不符合预期，请先处理，再让助手继续。

描述修改目标与验证方式​

向助手说明一个可观察的结果，而不是列出工具调用。明确场景或资源范围、必须保留的约束，以及如何证明任务完成。

改善当前场景中车辆展示区的光照，不要移动车辆或摄像机，尽量复用已有灯光。
完成后捕获编辑器视口、启动场景并捕获运行结果，报告所有控制台错误。

助手可以检查和编辑实体、组件、脚本、资源、场景、项目设置、模板、动画数据、构建和版本控制状态。让它根据目标选择所需工具。

验证运行结果​

场景或行为修改不能只检查源码。应让助手：

  1. 捕获编辑器视口，检查构图与所选对象。
  2. 启动一个 Launch 实例。
  3. 捕获运行中的应用。
  4. 读取运行时日志，并查询相关实体状态。
  5. 涉及交互时，注入键盘、鼠标或触摸输入。
  6. 验证完成后停止 Launch 实例。

请允许 PlayCanvas 编辑器来源弹出窗口，使服务器能打开 Launch 窗口。它会使用现有登录会话。如果实例已在运行，启动操作会连接到它而非重新启动，保留当前会话；指定图形设备等特定选项，则可强制重新启动。

下面演示助手审计旧版引擎 V1 项目，参考 PlayCanvas 文档，通过检查点迁移到引擎 V2 和 ESM 脚本，并验证运行结果。

检查或恢复​

让助手总结修改内容和观察到的证据，并在接受结果前自行检查场景。

  • 对近期独立修改，使用编辑器撤销／重做。
  • 如果要放弃整个任务，恢复检查点。
  • 接受较大改动后，创建新检查点。

除非明确需要相应破坏性操作，否则不要要求助手硬重置、删除分支、恢复检查点或删除项目数据。

何时改用 VS Code 扩展​

如果助手只需修改文本资源，且你希望推送到 PlayCanvas 前先检查本地文件差异，请使用 VS Code 扩展工作流。需要直接访问编辑器、场景、资源、视口或运行时的任务，则使用 MCP。

故障排查​

编辑器无法连接​

确认 MCP 客户端正在运行服务器、客户端与编辑器端口一致，且没有其他编辑器占用连接。修改配置后应重启客户端。

如果面板停留在 Connecting 并报告浏览器阻止连接，请打开编辑器地址栏锁形菜单，允许 Apps on device。

首次连接超时​

首次运行 npx 可能需要下载包。下载完成后重新启动客户端。Codex 用户也可增大 ~/.codex/config.toml 中 [mcp_servers.playcanvas] 的 startup_timeout_sec。

Launch 无法打开​

允许编辑器来源弹出窗口，关闭现有 Launch 窗口，再让助手启动实例。

Launch 实例始终未连接​

Launch 窗口已打开，但运行时工具报告未连接时，请重新加载编辑器以获取当前构建，再次启动实例。

助手操作了错误项目​

MCP 工具始终操作已连接编辑器中打开的项目。请让助手通过 open_project 打开目标项目，或先断开连接、自行打开项目并重连，再继续修改。

警告

服务器通过当前编辑器会话执行操作，可以删除实体、资源、构建和分支，以及重置项目状态。允许这些操作前应先检查，较大改动前请创建检查点。