Three.js DevTools MCP

threejs-devtools-mcp

用于实时检查 Three.js 场景、在浏览器中即时尝试更改并将其转换为代码的 MCP 服务。69 个工具涵盖对象、材质、着色器、纹理、动画、性能和内存，以及网站审计、视频帧捕获和 Playwright 辅助工具。

无需更改项目。 适用于原生 Three.js 和 React Three Fiber，支持 WebGLRenderer 和 WebGPURenderer。

设置

1. 添加 MCP 服务

claude mcp add threejs-devtools-mcp -- npx threejs-devtools-mcp

{
  "mcpServers": {
    "threejs-devtools-mcp": {
      "command": "npx",
      "args": ["-y", "threejs-devtools-mcp"]
    }
  }
}

{
  "mcpServers": {
    "threejs-devtools-mcp": {
      "command": "npx",
      "args": ["-y", "threejs-devtools-mcp"]
    }
  }
}

{
  "mcpServers": {
    "threejs-devtools-mcp": {
      "command": "npx",
      "args": ["-y", "threejs-devtools-mcp"]
    }
  }
}

{
  "servers": {
    "threejs-devtools-mcp": {
      "command": "npx",
      "args": ["-y", "threejs-devtools-mcp"]
    }
  }
}

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "threejs-devtools-mcp": {
      "type": "local",
      "command": ["npx", "-y", "threejs-devtools-mcp"],
      "enabled": true
    }
  }
}

2. 启动开发服务并打开浏览器

照常启动 Three.js 开发服务（npm run dev）。MCP 服务会自动从 package.json 检测端口，并打开 localhost:9222，注入开发者工具桥接程序。

保持浏览器标签页打开。 MCP 服务通过 WebSocket 桥接程序与场景通信。关闭标签页 = 工具停止工作。

3. 向 AI 询问场景相关问题

"show me the scene tree"
"why is my model invisible?"
"try the car in red"          ← live preview, nothing saved
"keep it"                     ← written into your code
"audit this site for mobile"
"record a 5-second clip at 60 fps"

仅查看效果 vs. 更改代码

每个工具都带有标签，方便你和 AI 始终了解哪些操作会影响文件：

每项实时预览更改都会被记录。pending_changes 会返回每项更改的之前 → 之后状态、可直接粘贴的代码（原生 Three.js 和 React Three Fiber），以及在项目中的位置。revert_changes 可在浏览器中撤销这些更改。

用于网站和视频

• web_audit：检查画布模糊（像素比率、缺少尺寸调整）、耗电过多（空闲或画面移出屏幕时仍在渲染）、纹理过大（尺寸超限、未使用 KTX2）、阴影开销过高、色彩空间错误以及绘制调用过多。每项问题都会附带修复方法。
• capture_frames：录制用于宣传短片和 Reels 的连续帧。时间经过虚拟化处理，因此即使场景渲染缓慢，输出也能以 30/60 fps 完美流畅。你会获得用于生成 MP4/WebM 的 ffmpeg 命令。

技能

在 Claude Code、Cursor 和其他客户端中，这些现成工作流会显示为斜杠命令：inspect-scene、try-look、apply-to-code、web-perf-audit、prepare-video、debug-invisible、playwright-setup。

Playwright & Puppeteer

三种连接方式，使用的工具都相同：你自己的浏览器（默认）、由服务启动的 Chrome（HEADLESS / CDP_PORT，可与 Playwright MCP 共享），或你自己的测试：

import { attachDevtools, waitForScene, threeCall } from 'threejs-devtools-mcp/playwright';

await attachDevtools(context, { connect: false });
await page.goto('http://localhost:5173');
await waitForScene(page);
expect((await threeCall(page, 'object_details', { name: 'Car' })).visible).toBe(true);

参见 Browsers, Puppeteer & Playwright。

浏览器内叠加层

内置的开发者工具面板，提供实时性能统计、交互式场景图、材质编辑器和 3D 对象预览。自动激活，也可通过 toggle_overlay 工具激活。

提示：为对象命名

未命名的对象在场景树中显示为 (unnamed)。为对象命名后，更容易查找和修改：

// Three.js
mesh.name = "player";

// React Three Fiber
<mesh name="player" geometry={geometry} material={material} />

文档

• 工具参考 — 按模式分类的全部 69 个工具、技能和参数
• Browsers, Puppeteer & Playwright — 连接模式、端到端测试和 CI 提示
• 高级设置 — 动画、场景导出、配置和传输方式
• Cursor 设置 — Cursor 分步指南
• 节省令牌的工作流 — 节省上下文的最佳实践

许可证

MIT