threejs-devtools-mcp

MCP server for inspecting and modifying Three.js scenes in real time — 47 tools for objects, materials, shaders, textures, animations, performance, memory diagnostics, and code generation.

Zero changes to your project. Works with vanilla Three.js, React Three Fiber, and any framework.

Setup

1. Add the MCP server

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"]
    }
  }
}

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 (Next.js → 3000, Vite → 5173, etc.) 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 in the browser. Close the tab → connection drops → tools stop working. Reopen localhost:9222 to reconnect.

3. Ask the AI about your scene

That's it. The AI sees the tools automatically and uses them when relevant. Just ask:

"use threejs-devtools-mcp to show me the scene tree"
"why is my model invisible? check with threejs-devtools"
"what materials are in the scene?"
"make the car red"
"find all transparent meshes"
"check for memory leaks"
"generate a React component from my model.glb"

Tip: Some AI clients (like Claude Code) pick up MCP tools automatically. Others (like Cursor) may need a nudge — mention threejs-devtools-mcp in your first prompt, after that the AI will keep using it.

Usage examples

Inspect the scene:

> "what's in the scene?"

The AI calls scene_tree and gets:
  Scene
    player [Mesh]
    ground [Mesh]
    lights [Group]
      sunLight [DirectionalLight] intensity=2
      ambientLight [AmbientLight] intensity=0.5
    trees [Group]
      tree_0 [InstancedMesh] instances=42

Debug a problem:

> "why is my player invisible?"

The AI checks object_details("player"):
  - visible: true, position: [0, 0, 0] ✓
  - material: MeshStandardMaterial, opacity: 0 ← found it!

> "fix it"
  → set_material_property(name="player", property="opacity", value=1)

Search and diagnose:

> "find all invisible meshes"
  → find_objects(type="Mesh", visible=false)
  → 3 hidden meshes found: oldPlayer, debugCube, unusedTerrain

> "check for memory leaks"
  → dispose_check
  → 12 orphaned geometries, 4 orphaned textures (not in scene but tracked by renderer)

> "how much VRAM am I using?"
  → memory_stats
  → Textures: 48.2 MB (top: skybox 16MB, terrain 8MB), Geometry: 3.1 MB

> "what changed in the scene?"
  → scene_diff (first call: saves snapshot)
  → scene_diff (second call: shows 5 objects moved, 2 materials changed color)

Generate React components from 3D models:

> "convert my character.glb to a React component"
  → gltf_to_r3f(filePath="public/character.glb")
  → Generated CharacterModel.tsx with useGLTF, useAnimations (Walk, Run, Idle)

Modify the scene live:

> "make the ground blue"
  → set_material_property(name="ground", property="color", value="#4488ff")

> "move the sun higher"
  → set_object_transform(name="sunLight", position=[0, 20, 0])

> "show me render stats"
  → renderer_info → draw calls: 230, triangles: 3.4M, textures: 27

Tip: name your objects

The scene tree uses object names to identify things. Unnamed objects show as (unnamed), making debugging harder. Always set .name:

// Three.js
const mesh = new THREE.Mesh(geometry, material);
mesh.name = "player";

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

How it works

AI Agent ←stdio/http→ MCP Server ←proxy :9222→ Dev Server (:3000)
                           ↕ WebSocket
                      Bridge (auto-injected into HTML)
                           ↕
                      Three.js scene

The proxy injects a bridge script into <head> before Three.js loads. The bridge captures Scene and Renderer via the official __THREE_DEVTOOLS__ API and exposes 47 tools to the AI agent.

Transports

| Transport | Command | Use case | |---|---|---| | stdio (default) | npx threejs-devtools-mcp | Claude Code, Claude Desktop, Cursor, Windsurf, VS Code | | Streamable HTTP | npx threejs-devtools-mcp-http | Cursor, Windsurf, or any HTTP MCP client |

The HTTP transport runs on http://localhost:9223/mcp (configurable via HTTP_PORT).

Configuration

All settings are optional. The defaults work out of the box.

| Env Variable | Default | Description | |---|---|---| | DEV_PORT | auto-detected | Dev server port to proxy | | BRIDGE_PORT | 9222 | Port the proxy listens on | | HTTP_PORT | 9223 | Streamable HTTP server port (http transport only) | | BROWSER | auto-open | Set to none to disable auto-opening the browser | | PUPPETEER | false | Set to true to launch via puppeteer instead of system browser | | HEADLESS | false | Set to true for headless Chrome (implies PUPPETEER=true, for CI) | | CHROME_PATH | auto-detected | Path to Chrome/Edge/Chromium executable |

Example — custom dev port, no browser auto-open:

{
  "mcpServers": {
    "threejs-devtools-mcp": {
      "command": "npx",
      "args": ["-y", "threejs-devtools-mcp"],
      "env": {
        "DEV_PORT": "5173",
        "BROWSER": "none"
      }
    }
  }
}

Example — headless mode for CI:

{
  "env": {
    "HEADLESS": "true",
    "DEV_PORT": "3000"
  }
}

Documentation

• Tools reference — all 47 tools with parameters
• Cursor setup — step-by-step guide for Cursor
• Token-efficient workflow — best practices for saving context

License

MIT