Skip to content
Back to search

threejs-devtools-mcp

Three.js MCP server — inspect and edit scenes, materials, shaders, lights in real time from any AI agent

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/dmitriygolub--threejs-devtools-mcp/badge.svg)](/listings/dmitriygolub--threejs-devtools-mcp)

HTML

<a href="/listings/dmitriygolub--threejs-devtools-mcp"><img src="/api/listings/dmitriygolub--threejs-devtools-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Add the MCP server

<details open> <summary><strong>Claude Code</strong></summary>

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

</details>

<details> <summary><strong>Claude Desktop</strong></summary>

Add to `claude_desktop_config.json`:

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

</details>

<details> <summary><strong>Cursor</strong></summary>

Add to `.cursor/mcp.json` in your project:

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

Or use the HTTP transport — see [Cursor setup guide](docs/cursor-setup.md).

</details>

<details> <summary><strong>Windsurf</strong></summary>

Add to `~/.codeium/windsurf/mcp_config.json`:

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

</details>

<details> <summary><strong>VS Code (Copilot)</strong></summary>

Add to `.vscode/mcp.json`:

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

</details>

<details> <summary><strong>OpenCode</strong></summary>

Add to `opencode.json` in your project:

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

</details>

2. Start your dev server and open the browser

Start your Three.js dev server as usual (`npm run dev`). The MCP server auto-detects the port from `package.json` and opens a browser at `localhost:9222` with the devtools bridge injected.

> **Keep the browser tab open.** The MCP server talks to your scene through a WebSocket bridge. Close the tab = tools stop working.

3. Ask the AI about your scene

"show me the scene tree"
"why is my model invisible?"
"make the car red"
"check for memory leaks"
"what's my FPS?"
"generate a React component from character.glb"

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 205 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # threejs-devtools-mcp
  2. [![npm version](https://img.shields.io/npm/v/threejs-devtools-mcp)](https://www.npmjs.com/package/threejs-devtools-mcp)
  3. [![license](https://img.shields.io/npm/l/threejs-devtools-mcp)](LICENSE)
  4. [![build](https://github.com/DmitriyGolub/threejs-devtools-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/DmitriyGolub/threejs-devtools-mcp/actions)
  5. [![MCP Registry](https://img.shields.io/badge/MCP-Registry-blue)](https://mcp-marketplace.io/server/io-github-dmitriygolub-threejs-devtools)
  6. MCP server for inspecting Three.js scenes in real time, trying changes live in the browser, and turning them into code. **69 tools** cover objects, materials, shaders, textures, animation, performance and memory, plus website audits, video frame capture and Playwright helpers.
  7. **Zero changes to your project.** Works with vanilla Three.js and React Three Fiber, on WebGLRenderer and WebGPURenderer.
  8. ![Annotated screenshot](docs/images/annotated.png)
  9. ## Setup
  10. ### 1. Add the MCP server
  11. <details open>
  12. <summary><strong>Claude Code</strong></summary>
  13. ```bash
  14. claude mcp add threejs-devtools-mcp -- npx threejs-devtools-mcp
  15. ```
  16. </details>
  17. <details>
  18. <summary><strong>Claude Desktop</strong></summary>
  19. Add to `claude_desktop_config.json`:
  20. ```json
  21. {
  22. "mcpServers": {
  23. "threejs-devtools-mcp": {
  24. "command": "npx",
  25. "args": ["-y", "threejs-devtools-mcp"]
  26. }
  27. }
  28. }
  29. ```
  30. </details>
  31. <details>
  32. <summary><strong>Cursor</strong></summary>
  33. Add to `.cursor/mcp.json` in your project:
  34. ```json
  35. {
  36. "mcpServers": {
  37. "threejs-devtools-mcp": {
  38. "command": "npx",
  39. "args": ["-y", "threejs-devtools-mcp"]
  40. }
  41. }
  42. }
  43. ```
  44. Or use the HTTP transport — see [Cursor setup guide](docs/cursor-setup.md).
  45. </details>
  46. <details>
  47. <summary><strong>Windsurf</strong></summary>
  48. Add to `~/.codeium/windsurf/mcp_config.json`:
  49. ```json
  50. {
  51. "mcpServers": {
  52. "threejs-devtools-mcp": {
  53. "command": "npx",
  54. "args": ["-y", "threejs-devtools-mcp"]
  55. }
  56. }
  57. }
  58. ```
  59. </details>
  60. <details>
  61. <summary><strong>VS Code (Copilot)</strong></summary>
  62. Add to `.vscode/mcp.json`:
  63. ```json
  64. {
  65. "servers": {
  66. "threejs-devtools-mcp": {
  67. "command": "npx",
  68. "args": ["-y", "threejs-devtools-mcp"]
  69. }
  70. }
  71. }
  72. ```
  73. </details>
  74. <details>
  75. <summary><strong>OpenCode</strong></summary>
  76. Add to `opencode.json` in your project:
  77. ```json
  78. {
  79. "$schema": "https://opencode.ai/config.json",
  80. "mcp": {
  81. "threejs-devtools-mcp": {
  82. "type": "local",
  83. "command": ["npx", "-y", "threejs-devtools-mcp"],
  84. "enabled": true
  85. }
  86. }
  87. }
  88. ```
  89. </details>
  90. ### 2. Start your dev server and open the browser
  91. Start your Three.js dev server as usual (`npm run dev`). The MCP server auto-detects the port from `package.json` and opens a browser at `localhost:9222` with the devtools bridge injected.
  92. > **Keep the browser tab open.** The MCP server talks to your scene through a WebSocket bridge. Close the tab = tools stop working.
  93. ### 3. Ask the AI about your scene
  94. ```
  95. "show me the scene tree"
  96. "why is my model invisible?"
  97. "try the car in red" ← live preview, nothing saved
  98. "keep it" ← written into your code
  99. "audit this site for mobile"
  100. "record a 5-second clip at 60 fps"
  101. ```
  102. ## Look now vs. change the code
  103. Every tool is labelled, so you and the AI always know what touches your files:
  104. | | Tools | Your code |
  105. |---|---|---|
  106. | **Inspect** | `scene_tree`, `material_details`, `web_audit`, screenshots… | untouched |
  107. | **Live preview** | `set_material_property`, `set_light`, `set_camera`… | untouched; lost on page reload |
  108. | **Debug visual** | wireframe, bounding boxes, helpers, overlay | untouched; never needed in code |
  109. | **For code** | `pending_changes`, `gltf_to_r3f` | the AI writes this into your source |
  110. Every live-preview change is recorded. `pending_changes` returns each one as **before → after with ready-to-paste code** (vanilla Three.js and React Three Fiber) and where to find it in your project. `revert_changes` undoes them in the browser.
  111. ## For websites and videos
  112. - **`web_audit`**: checks for a blurry canvas (pixel ratio, missing resize), battery drain (rendering while idle or off-screen), heavy textures (oversized, not KTX2), expensive shadows, wrong color space and too many draw calls. Each finding comes with the fix.
  113. - **`capture_frames`**: records a frame sequence for promo clips and reels. Time is virtualised, so the output is perfectly smooth at 30/60 fps even if your scene renders slowly. You get the `ffmpeg` command for MP4/WebM.
  114. ## Skills
  115. Ready-made workflows show up as slash commands in Claude Code, Cursor and other clients: `inspect-scene`, `try-look`, `apply-to-code`, `web-perf-audit`, `prepare-video`, `debug-invisible`, `playwright-setup`.
  116. ## Playwright & Puppeteer
  117. Three ways to connect, same tools in all of them: your own browser (default), a Chrome launched by the server (`HEADLESS` / `CDP_PORT`, shareable with Playwright MCP), or your own tests:
  118. ```ts
  119. import { attachDevtools, waitForScene, threeCall } from 'threejs-devtools-mcp/playwright';
  120. await attachDevtools(context, { connect: false });
  121. await page.goto('http://localhost:5173');
  122. await waitForScene(page);
  123. expect((await threeCall(page, 'object_details', { name: 'Car' })).visible).toBe(true);
  124. ```
  125. See [Browsers, Puppeteer & Playwright](docs/playwright.md).
  126. ## In-browser overlay
  127. A built-in devtools panel with live performance stats, interactive scene graph, material editor, and 3D object preview. Activated automatically or via the `toggle_overlay` tool.
  128. ![Overlay panel](docs/images/example.png)
  129. ## Tip: name your objects
  130. Unnamed objects show as `(unnamed)` in the scene tree. Named objects are easier to find and modify:
  131. ```js
  132. // Three.js
  133. mesh.name = "player";
  134. ```
  135. ```jsx
  136. // React Three Fiber
  137. <mesh name="player" geometry={geometry} material={material} />
  138. ```
  139. ## Documentation
  140. - [Tools reference](docs/tools.md) — all 69 tools by mode, skills, parameters
  141. - [Browsers, Puppeteer & Playwright](docs/playwright.md) — connection modes, e2e tests, CI tips
  142. - [Advanced setup](docs/advanced.md) — animations, scene export, configuration, transports
  143. - [Cursor setup](docs/cursor-setup.md) — step-by-step guide for Cursor
  144. - [Token-efficient workflow](docs/workflow.md) — best practices for saving context
  145. ## License
  146. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.